# Quickstart: Portfolio Triage Arrival Context

## Goal

Implement a small continuity layer that preserves why a tenant was opened from portfolio triage, what the operator should do next, and how to return to the portfolio flow, without adding persistence or new posture logic.

## Implementation Sequence

1. Add the request-scoped arrival-context core.
   - Create `PortfolioArrivalContext`, `PortfolioArrivalContextToken`, and `PortfolioArrivalContextResolver` under `apps/platform/app/Support/PortfolioTriage/`.
   - Add focused unit coverage for the token and resolver seam under `apps/platform/tests/Unit/Support/PortfolioTriage/`.
   - Reuse the existing base64url token pattern already used elsewhere in the repo.

2. Emit arrival tokens from portfolio sources.
   - Update workspace overview drilldown builders in `apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php`.
   - Update tenant-registry tenant-open URLs when triage filters are active in `apps/platform/app/Filament/Resources/TenantResource.php` and `apps/platform/app/Filament/Resources/TenantResource/Pages/ListTenants.php`.

3. Render continuity on the tenant dashboard.
   - Add `TenantTriageArrivalContinuity` under `apps/platform/app/Filament/Widgets/Tenant/`.
   - Add its Blade view under `apps/platform/resources/views/filament/widgets/tenant/`.
   - Register the widget first in `apps/platform/app/Filament/Pages/TenantDashboard.php`.

4. Reuse deeper continuity surfaces instead of replacing them.
   - Keep `backup_health_reason` on backup-set destinations.
   - Keep `recovery_posture_reason` on restore-run list or detail destinations.
   - Keep subheading continuity in `ListBackupSets`, `ListRestoreRuns`, and `ViewRestoreRun` intact.

5. Add regression coverage.
   - Add workspace overview arrival-context tests.
   - Add tenant-registry filtered return-path tests.
   - Add tenant-dashboard rendering and RBAC degradation tests.
   - Add tenant-dashboard performance coverage so arrival-context resolution stays request-local and query-safe.
   - Keep existing workspace overview content, tenant-registry recovery triage, and backup or restore continuity regressions green.

## Suggested Test Files

- `apps/platform/tests/Unit/Support/PortfolioTriage/PortfolioArrivalContextTokenTest.php`
- `apps/platform/tests/Unit/Support/PortfolioTriage/PortfolioArrivalContextResolverTest.php`
- `apps/platform/tests/Feature/Filament/WorkspaceOverviewArrivalContextTest.php`
- `apps/platform/tests/Feature/Filament/TenantRegistryArrivalContextTest.php`
- `apps/platform/tests/Feature/Filament/TenantDashboardArrivalContextTest.php`
- `apps/platform/tests/Feature/Filament/TenantDashboardArrivalContextPerformanceTest.php`
- `apps/platform/tests/Feature/Rbac/TenantDashboardArrivalContextVisibilityTest.php`
- `apps/platform/tests/Feature/Filament/BackupSetListContinuityTest.php`
- `apps/platform/tests/Feature/Filament/RestoreRunListContinuityTest.php`

## Existing Regression Suites To Keep Green

- `apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php`
- `apps/platform/tests/Feature/Filament/TenantRegistryRecoveryTriageTest.php`

## Minimum Verification Commands

Run all commands through Sail from `apps/platform`.

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/PortfolioTriage/PortfolioArrivalContextTokenTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/PortfolioTriage/PortfolioArrivalContextResolverTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewArrivalContextTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantRegistryArrivalContextTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardArrivalContextTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardArrivalContextPerformanceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantDashboardArrivalContextVisibilityTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewContentTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantRegistryRecoveryTriageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BackupSetListContinuityTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/RestoreRunListContinuityTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## Manual Acceptance Checklist

1. Open a flagged tenant from workspace overview backup attention and verify the tenant dashboard explains the backup concern before deeper widgets.
2. Open a flagged tenant from workspace overview recovery attention and verify the dashboard explains the recovery concern and recommended next action.
3. Open a tenant from filtered registry triage and verify the return link preserves filters and sort.
4. Open the tenant dashboard directly without any arrival token and verify no continuity block appears.
5. Use a role with limited destination access and verify the continuity block stays truthful without exposing a broken CTA.

## Deployment Notes

- No migrations are required.
- No new assets are expected. Existing Filament asset deployment behavior remains unchanged.
- The feature should degrade cleanly if old or malformed links reach the tenant dashboard.