TenantAtlas/specs/187-portfolio-triage-arrival-context/quickstart.md

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.

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.