# Quickstart: Tenant Selector and Remembered Context Enforcement

## Goal

Implement Spec 147 so tenant selection, remembered tenant context, and route legitimacy follow one workspace-first model across the header selector, choose-tenant page, workspace switching, tenant-bound routes, and canonical workspace record viewers.

## Implementation Steps

1. Consolidate remembered tenant validation in `app/Support/Workspaces/WorkspaceContext.php`.
   - Add or refine shared methods that return only validated remembered tenant context.
   - Ensure stale values clear deterministically for workspace mismatch, missing tenant, entitlement loss, and selector-ineligible lifecycle.

2. Converge selector membership on `app/Services/Tenants/TenantOperabilityService.php`.
   - Remove or simplify any custom header-selector queries that can diverge from `ChooseTenant`.
   - Keep active-lane semantics aligned across the header context bar, choose-tenant page, and `SelectTenantController`.

3. Refine shell resolution in `app/Support/OperateHub/OperateHubShell.php`.
   - Prefer route-authoritative tenants on tenant-bound pages.
   - Prefer validated remembered tenant only for workspace-level active-lane convenience.
   - Preserve canonical page legitimacy when selected tenant differs or is absent.

4. Update in-scope UI surfaces.
   - Header context bar: show only eligible active-lane tenants and keep “clear tenant scope” behavior workspace-safe.
   - Choose-tenant page: preserve the same active-lane meaning and empty-state framing.
   - Managed-tenant administration: keep onboarding and archived tenants discoverable and keep `/admin/tenants` usable without selected tenant state.
   - Tenant-bound and canonical pages: keep mismatch informational and non-blocking.

5. Audit workspace-context global search.
   - Ensure no-selected-tenant workspace context does not use remembered tenant state to surface tenant-owned results or hints.

6. Add regression coverage.
   - Unit tests for remembered-context invalidation and shell resolution.
   - Feature tests for selector membership, managed-tenant discoverability, workspace switching, no-selected-tenant workspace behavior, global-search safety, tenant-bound mismatch, and canonical run mismatch.

7. Review affected list surfaces against `docs/product/standards/list-surface-review-checklist.md`.
   - Validate that `/admin/tenants` and `/admin/operations` still satisfy the established list-surface standards while selector semantics and no-context fallback are hardened.

8. Validate render and query safety.
   - Confirm the focused regression suite covers the shell, choose-tenant page, tenant detail, and canonical operations viewer without introducing material query-count regressions.

## Suggested Test Commands

Run focused tests through Sail:

```bash
vendor/bin/sail artisan test --compact tests/Unit
vendor/bin/sail artisan test --compact tests/Feature/Operations
vendor/bin/sail artisan test --compact tests/Feature/Filament
vendor/bin/sail artisan test --compact tests/Feature/Rbac
```

Format changed files:

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

## Manual Verification Checklist

1. Select an active tenant from the header selector and confirm the tenant dashboard or active-lane flow resolves normally.
2. Confirm onboarding and archived tenants do not appear in the header selector or choose-tenant page.
3. Switch workspaces and confirm the previous workspace's remembered tenant does not remain active in the new workspace.
4. Clear tenant scope and confirm `/admin` and `/admin/operations` remain usable with no selected tenant.
5. Confirm `/admin/tenants` remains usable with no selected tenant and still exposes onboarding or archived records through the intended management surfaces.
6. Open `/admin/tenants/{tenant}` for an authorized onboarding or archived tenant and confirm the page remains valid.
7. Verify workspace-context global search with no selected tenant does not reveal tenant-owned results because of remembered tenant state.
8. Open `/admin/operations/{run}` with mismatched or empty selected tenant context and confirm the canonical page still renders with non-blocking mismatch framing.
9. Review `/admin/tenants` and `/admin/operations` against `docs/product/standards/list-surface-review-checklist.md` and confirm inspection, empty-state, and filter behavior remain compliant.
10. Confirm the focused regression suite or local instrumentation shows no material query-count regression on the shell, choose-tenant page, tenant detail, and canonical operations viewer flows.