# Quickstart: Workspace Chooser v1

**Feature**: 107-workspace-chooser | **Date**: 2026-02-22

## Prerequisites

- Branch: `107-workspace-chooser` checked out
- Sail running: `vendor/bin/sail up -d`
- Existing workspace + user fixtures (factory-based)

## Implementation Order

### Phase A: Foundation (no visible changes)

1. **Add `AuditActionId` enum cases** — `WorkspaceAutoSelected`, `WorkspaceSelected`
2. **Extract `WorkspaceRedirectResolver`** — shared tenant-count branching helper (DRY the 4 current copies)
3. **Tests for redirect resolver** — verify 0/1/>1 tenant branching

### Phase B: Middleware Refactor (core behavior change)

4. **Refactor `EnsureWorkspaceSelected`** — implement 7-step algorithm from spec
   - Step 1: workspace-optional path bypass (keep existing `isWorkspaceOptionalPath()`)
   - Step 2: `?choose=1` handling (new)
   - Step 3: stale session detection + flash warning (enhanced)
   - Step 4-5: single membership auto-resume + audit (new)
   - Step 6: `last_workspace_id` auto-resume + audit (new)
   - Step 7: fallback to chooser (existing)
5. **Middleware tests** — all 7 steps covered

### Phase C: Chooser Page Upgrade (UI changes)

6. **Refactor `ChooseWorkspace` page**:
   - Remove "Create workspace" header action
   - Add `withCount('tenants')` to query
   - Load membership roles keyed by workspace_id
   - Expose `getWorkspaceRole()` and `getWorkspaceMemberships()` for Blade
7. **Update `choose-workspace.blade.php`**:
   - Add role badge per card
   - Add tenant count per card
   - Add "Manage workspaces" link (capability-gated)
   - Update empty state (spec copy)
   - Replace form POST with `wire:click="selectWorkspace({{ $workspace->id }})"`
8. **Add audit logging in `selectWorkspace()`** — emit `workspace.selected` with metadata
9. **Chooser page tests** — metadata display, empty state, manage link visibility, audit events

### Phase D: User Menu Integration

10. **Register "Switch workspace" in `AdminPanelProvider`** — `userMenuItems()` with visibility condition
11. **User menu tests** — visible when >1 workspace, hidden when 1

### Phase E: Cleanup & Verification

12. **Replace inline tenant-branching** in `SwitchWorkspaceController` and `routes/web.php` with `WorkspaceRedirectResolver`; add `WorkspaceAuditLogger::log()` for `context_bar` switch path in `SwitchWorkspaceController`
13. **Run full test suite** — verify no regressions
14. **Pint formatting** — `vendor/bin/sail bin pint --dirty`
15. **Commit + push**

## Key Files to Understand First

| File | Why |
|------|-----|
| `app/Http/Middleware/EnsureWorkspaceSelected.php` | The middleware being refactored |
| `app/Filament/Pages/ChooseWorkspace.php` | The page being upgraded |
| `app/Support/Workspaces/WorkspaceContext.php` | The workspace session manager |
| `app/Services/Audit/WorkspaceAuditLogger.php` | Where audit events are emitted |
| `app/Support/Audit/AuditActionId.php` | Where enum cases are added |
| `app/Http/Controllers/SwitchWorkspaceController.php` | POST switch (redirect resolver integration) |
| `routes/web.php` (lines 36-82) | `/admin` route with duplicated branching |

## Verification Commands

```bash
# Run workspace-related tests
vendor/bin/sail artisan test --compact tests/Feature/Workspaces/

# Run specific middleware test
vendor/bin/sail artisan test --compact --filter=EnsureWorkspaceSelected

# Run chooser page test
vendor/bin/sail artisan test --compact --filter=ChooseWorkspacePage

# Format
vendor/bin/sail bin pint --dirty

# Full suite
vendor/bin/sail artisan test --compact
```