# 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 admin user menu uses this exact destination today, while the context bar still points to the workspace CRUD index. The `?choose=1` parameter is the established convention for bypassing workspace auto-resume and forcing the chooser when the user explicitly intends to switch.

**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.

## 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.