# Quickstart: Workspace Home & Admin Landing

**Feature**: 129-workspace-admin-home | **Date**: 2026-03-09

## Scope

This feature turns `/admin` into the canonical workspace-level home by:

- adding a real workspace overview page,
- preserving workspace selection as the only precondition,
- stopping normal `/admin` access from silently redirecting into tenant context,
- exposing a primary `Overview` navigation item,
- adding bounded workspace-safe summary, attention, and recent-operation surfaces,
- keeping `Switch workspace` and `Manage workspaces` distinct.

## Implementation order

1. Create the new workspace overview page under the existing admin panel.
2. Update `/admin` landing behavior so selected-workspace requests render the overview instead of delegating to tenant branching.
3. Constrain direct `/admin` requests without workspace context to chooser-first behavior in the workspace-selection middleware.
4. Register `Overview` as the first relevant admin navigation item and confirm brand-logo navigation resolves back to `/admin`.
5. Add capability-safe summary cards and bounded recent or needs-attention surfaces using existing canonical destinations.
6. Add quick actions for choose tenant, operations, alerts, switch workspace, and manage workspaces when authorized.
7. Update or replace legacy tests that currently assert `/admin` redirects to tenant chooser or tenant dashboard.
8. Run focused Sail-based tests.
9. Run Pint on dirty files.

## Reference files

- [app/Providers/Filament/AdminPanelProvider.php](../../../app/Providers/Filament/AdminPanelProvider.php)
- [routes/web.php](../../../routes/web.php)
- [app/Http/Middleware/EnsureWorkspaceSelected.php](../../../app/Http/Middleware/EnsureWorkspaceSelected.php)
- [app/Support/Workspaces/WorkspaceRedirectResolver.php](../../../app/Support/Workspaces/WorkspaceRedirectResolver.php)
- [app/Filament/Pages/ChooseWorkspace.php](../../../app/Filament/Pages/ChooseWorkspace.php)
- [app/Filament/Pages/ChooseTenant.php](../../../app/Filament/Pages/ChooseTenant.php)
- [app/Support/Middleware/EnsureFilamentTenantSelected.php](../../../app/Support/Middleware/EnsureFilamentTenantSelected.php)
- [tests/Feature/Filament/AdminHomeRedirectsToChooseTenantWhenWorkspaceSelectedTest.php](../../../tests/Feature/Filament/AdminHomeRedirectsToChooseTenantWhenWorkspaceSelectedTest.php)
- [tests/Feature/Filament/LoginRedirectsToChooseWorkspaceWhenMultipleWorkspacesTest.php](../../../tests/Feature/Filament/LoginRedirectsToChooseWorkspaceWhenMultipleWorkspacesTest.php)
- [tests/Feature/Filament/WorkspaceOverviewLandingTest.php](../../../tests/Feature/Filament/WorkspaceOverviewLandingTest.php)
- [tests/Feature/Filament/WorkspaceOverviewNavigationTest.php](../../../tests/Feature/Filament/WorkspaceOverviewNavigationTest.php)
- [tests/Feature/Filament/WorkspaceOverviewContentTest.php](../../../tests/Feature/Filament/WorkspaceOverviewContentTest.php)
- [tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php](../../../tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php)
- [tests/Feature/Filament/WorkspaceOverviewOperationsTest.php](../../../tests/Feature/Filament/WorkspaceOverviewOperationsTest.php)
- [tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php](../../../tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php)
- [tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php](../../../tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php)

## Suggested validation commands

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/AdminHomeRedirectsToChooseTenantWhenWorkspaceSelectedTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/LoginRedirectsToChooseWorkspaceWhenMultipleWorkspacesTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewLandingTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewNavigationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewContentTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewOperationsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/ChooseTenantRequiresWorkspaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/AdminWorkspaceRoutesGuardTest.php
vendor/bin/sail bin pint --dirty --format agent
```

## Expected outcome

- `/admin` is a real workspace-level home whenever a workspace is selected.
- Direct `/admin` access without workspace context goes to choose-workspace instead of silently auto-resuming into tenant context.
- The admin brand logo and primary navigation lead back to the workspace home.
- Workspace home content is capability-aware, tenantless by default, bounded, and non-polling by default.
- Legacy tenant-forcing assumptions are contained to explicit chooser or tenant-required flows.