# Research: Workspace Switch Semantic Fix

**Feature**: 121-workspace-switch-fix | **Date**: 2026-03-07

## R1: Canonical destination for intentional workspace switching

**Decision**: Use `ChooseWorkspace::getUrl(panel: 'admin').'?choose=1'` as the context-bar target for `Switch workspace`.

**Rationale**: The codebase already treats the chooser page as the canonical manual-switch experience. The `?choose=1` parameter is the established convention for bypassing workspace auto-resume and forcing the chooser when the user explicitly intends to switch. Anchoring switching in the context bar avoids mixing workspace context controls into the top-right account/user menu.

**Alternatives considered**:
- Link to `route('filament.admin.resources.workspaces.index')`: rejected because that is the management surface (`Manage workspaces`), not the switch flow.
- Link to `/admin/choose-workspace` without `?choose=1`: rejected because the codebase already documents `?choose=1` as the explicit forced-chooser contract for intentional switching.

## R2: Post-selection redirect behavior after entering the chooser

**Decision**: Preserve the chooser’s existing redirect behavior after a workspace is selected.

**Rationale**: `ChooseWorkspace::selectWorkspace()` already resolves post-selection flow through `WorkspaceIntendedUrl::consume()` and `WorkspaceRedirectResolver::resolve()`. That behavior is covered by existing tests and is outside this spec’s scope. The fix is semantic routing into the chooser, not a redesign of what happens after a user selects a workspace.

**Alternatives considered**:
- Always redirect back to the current page after selection: rejected because it would change established chooser behavior and broaden scope beyond a low-risk semantic correction.
- Always redirect to one fixed landing page: rejected because it would bypass the existing tenant-count branching contract.

## R3: Separation between switching and management

**Decision**: Keep workspace management reachable only through its existing dedicated administrative destinations, while the context bar becomes chooser-only.

**Rationale**: The chooser page already exposes a capability-aware `Manage workspaces` link for eligible roles, and the workspace resource itself is explicitly labeled `Manage workspaces`. This preserves the intended split between operational context switching and workspace CRUD administration.

**Alternatives considered**:
- Add both switch and management links to the same context-bar action surface: rejected because it would continue the semantic conflation the spec is correcting.
- Hide workspace management entirely from chooser-adjacent flows: rejected because the current dedicated management affordances are valid and already capability-aware.

## R5: Keep switching out of the top-right user menu

**Decision**: Remove the admin panel `Switch workspace` user-menu shortcut and keep workspace switching as a context-bar-only affordance.

**Rationale**: Workspace selection changes application context, not user-account state. Keeping the switcher in the context bar makes it visible in both admin and tenant panels through the shared render hook, while the user menu stays focused on profile, theme, and session actions.

**Alternatives considered**:
- Keep the user-menu shortcut as a secondary path: rejected because it duplicates the context action and creates cross-panel inconsistency unless every panel adopts it.
- Add the shortcut to the tenant panel user menu too: rejected because it still places a context switch under an account-oriented surface.

## R4: Smallest reliable test strategy

**Decision**: Extend response-level topbar rendering coverage in `HeaderContextBarTest`, and rely on existing workspace chooser/navigation tests for regression protection around management and forced chooser behavior.

**Rationale**: The bug lives in a rendered Blade partial in the admin topbar, so the most direct regression test is an HTTP response assertion on a real admin page that includes the context bar. Existing tests already cover chooser routing semantics, forced chooser behavior, chooser management-link visibility, and navigation hub separation.

**Alternatives considered**:
- Test only the chooser Livewire page: rejected because it would not assert the actual broken context-bar link.
- Add browser-only coverage: rejected because existing response-based feature tests already cover the required semantic contract at lower cost.