refactor: refine audio stream handling, simplify error message extraction, and update test assertions.

.claude/hookify.block-biome-ignore-bash.local.md

@@ -0,0 +1,29 @@
+---
+name: block-biome-ignore-bash
+enabled: true
+event: bash
+action: block
+pattern: (biome-ignore|@ts-ignore|@ts-expect-error|@ts-nocheck|eslint-disable).*\.(js|jsx|ts|tsx|mjs|cjs)
+---
+
+🚫 **BLOCKED: Bash Command Inserting Type/Lint Suppression**
+
+You are attempting to use a bash command to insert a lint or type suppression comment into a JavaScript/TypeScript file.
+
+**Detected suppression patterns:**
+- `biome-ignore` - Biome linter suppression
+- `@ts-ignore` - TypeScript error suppression
+- `@ts-expect-error` - TypeScript expected error suppression
+- `@ts-nocheck` - Disables TypeScript checking for entire file
+- `eslint-disable` - ESLint rule suppression
+
+**Why this is blocked:**
+Type and lint suppressions hide problems rather than fixing them. Using bash to circumvent file editing rules is not acceptable.
+
+**What you MUST do instead:**
+1. **Fix the root cause** - Properly type your code or fix the lint violation
+2. **Refactor if needed** - If the type system can't express your intent, restructure the code
+3. **Use proper typing** - Add explicit type annotations, type guards, or type assertions
+4. **Ask for help** - If genuinely stuck, ask the user for guidance on the correct approach
+
+**Remember:** A clean codebase has zero suppression comments. Every suppression is a bug waiting to happen.

.claude/hookify.block-biome-ignore.local.md

@@ -0,0 +1,36 @@
+---
+name: block-biome-ignore
+enabled: true
+event: file
+action: block
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: \.(js|jsx|ts|tsx|mjs|cjs)$
+  - field: new_text
+    operator: regex_match
+    pattern: //\s*biome-ignore|//\s*@ts-ignore|//\s*@ts-expect-error|//\s*@ts-nocheck|//\s*eslint-disable|/\*\s*eslint-disable
+---
+
+🚫 **BLOCKED: Type/Lint Suppression Comment Detected**
+
+You are attempting to add a lint or type suppression comment to a JavaScript/TypeScript file.
+
+**Detected suppression patterns:**
+- `// biome-ignore` - Biome linter suppression
+- `// @ts-ignore` - TypeScript error suppression
+- `// @ts-expect-error` - TypeScript expected error suppression
+- `// @ts-nocheck` - Disables TypeScript checking for entire file
+- `// eslint-disable` - ESLint rule suppression
+- `/* eslint-disable */` - ESLint block suppression
+
+**Why this is blocked:**
+Type and lint suppressions hide problems rather than fixing them. They accumulate as technical debt and mask real issues.
+
+**What you MUST do instead:**
+1. **Fix the root cause** - Properly type your code or fix the lint violation
+2. **Refactor if needed** - If the type system can't express your intent, restructure the code
+3. **Use proper typing** - Add explicit type annotations, type guards, or type assertions
+4. **Ask for help** - If genuinely stuck, ask the user for guidance on the correct approach
+
+**Remember:** A clean codebase has zero suppression comments. Every suppression is a bug waiting to happen.

docs/sprints/phase-ongoing/sprint-organization/api.md

@@ -0,0 +1,84 @@
+# Client API Reorganization Plan
+
+The `client/src/api` directory is currently a flat list of adapters, core logic, and helpers, mixing different abstraction layers. This document outlines a plan to reorganize them into logical layers to improve maintainability and separation of concerns.
+
+## Analysis
+
+### 1. Adapters (Implementations)
+**Target Directory**: `client/src/api/adapters/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `cached-adapter.ts` | `cachedAPI` | `index.ts`, `index.test.ts` | `interface`, `types`, `cached/*` | `cached-adapter.test.ts` |
+| `cached/*` | (Various API sections) | `cached-adapter.ts` | `interface`, `types` | N/A |
+| `mock-adapter.ts` | `mockAPI` | `index.ts`, `index.test.ts` | `interface`, `types`, `mock-data`, `mock-stream` | `mock-adapter.test.ts` |
+| `mock-data.ts` | `generateId`, `generateMeeting`, ... | `mock-adapter.ts` | `types` | `mock-data.test.ts` |
+| `mock-transcription-stream.ts` | `MockTranscriptionStream` | `mock-adapter.ts` | `interface`, `types` | `mock-transcription-stream.test.ts` |
+| `tauri-adapter/` | (Directory) | `index.ts` | `interface`, `types`, `@tauri-apps/*` | `tauri-adapter/**/*.test.ts` |
+| `tauri-constants.ts` | `TauriCommands`, `TauriEvents` | `tauri-adapter`, `constants.ts` | N/A | `tauri-constants.test.ts` |
+| `offline-defaults.ts` | `offlineServerInfo`, ... | `cached-adapter`, `cached/base.ts` | `types` | N/A |
+
+### 2. Core Logic & State
+**Target Directory**: `client/src/api/core/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `connection-state.ts` | `getConnectionState`, `setConnectionMode` | `index.ts`, `reconnection.ts`, `hooks` | N/A | `connection-state.test.ts` |
+| `reconnection.ts` | `startReconnection`, `onReconnected` | `index.ts`, `hooks` | `interface`, `connection-state` | `reconnection.test.ts` |
+| `error-utils.ts` | `extractErrorMessage`, `classifyError` | `adapters/*`, `helpers.ts` | `types` | N/A (Tested in `helpers.test.ts`) |
+| `helpers.ts` | `delay`, `paginate`, `stateToGrpcEnum` | `adapters/*` | `types`, `error-utils` | `helpers.test.ts` |
+| `constants.ts` | `Timing`, `IdentityDefaults` | `adapters/*` | `tauri-constants` | N/A |
+| `transcription-stream.ts` | `TranscriptionStream` (interface) | `interface.ts`, `adapters/*` | `types` | N/A |
+
+### 3. Contracts (Root)
+**Target Directory**: `client/src/api/` (Keep in root)
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `index.ts` | `initializeAPI`, `getAPI` | **Application Entry** | `adapters/*`, `core/*`, `interface` | `index.test.ts` |
+| `interface.ts` | `NoteFlowAPI` | **Everywhere** | `types`, `core/streams` | N/A |
+| `types/` | (Type definitions) | **Everywhere** | N/A | `types/**/*.test.ts` |
+
+## Execution Plan
+
+1.  **Create Directories**: `client/src/api/adapters/{cached,mock,tauri}`, `client/src/api/core`.
+2.  **Move Core Files**:
+    *   `connection-state.ts` -> `core/connection.ts`
+    *   `reconnection.ts` -> `core/reconnection.ts`
+    *   `constants.ts` -> `core/constants.ts`
+    *   `helpers.ts` -> `core/helpers.ts`
+    *   `error-utils.ts` -> `core/errors.ts`
+    *   `transcription-stream.ts` -> `core/streams.ts` (Rename to avoid confusion with implementation)
+3.  **Move Adapters**:
+    *   `cached-adapter.ts` -> `adapters/cached/index.ts`
+    *   `client/src/api/cached/` -> `adapters/cached/implementations/` (or flatten into `adapters/cached/`)
+    *   `offline-defaults.ts` -> `adapters/cached/defaults.ts`
+    *   `mock-adapter.ts` -> `adapters/mock/index.ts`
+    *   `mock-data.ts` -> `adapters/mock/data.ts`
+    *   `mock-transcription-stream.ts` -> `adapters/mock/stream.ts`
+    *   `tauri-adapter/` content -> `adapters/tauri/`
+    *   `tauri-constants.ts` -> `adapters/tauri/constants.ts` (Update root `constants.ts` to re-export if needed, or update imports)
+4.  **Move Tests**: Move all associated tests (`.test.ts`) alongside their source files.
+    *   *Note*: `tauri-transcription-stream.test.ts` is currently in root, move to `adapters/tauri/stream.test.ts`.
+5.  **Update Imports**:
+    *   Update relative imports within the moved files.
+    *   Update usages in `index.ts` and `interface.ts`.
+    *   Update usages across the codebase (using search & replace).
+6.  **Cleanup**:
+    *   Ensure `client/src/api/constants.ts` properly re-exports Tauri constants if they are still needed globally, or update call sites to import from `adapters/tauri/constants`.
+
+## Impacted Tests
+*   `api/index.test.ts`
+*   `api/cached-adapter.test.ts`
+*   `api/mock-adapter.test.ts`
+*   `api/connection-state.test.ts`
+*   `api/reconnection.test.ts`
+*   `api/tauri-transcription-stream.test.ts`
+*   `api/helpers.test.ts`
+*   `hooks/use-*.test.ts` (Indirectly via imports)
+
+## Recommendations
+*   **Flatten Cached Adapter**: The `cached/` subdirectory currently contains one file per feature. This is good structure, keep it within `adapters/cached/`.
+*   **Unified Stream Interface**: Ensure `TranscriptionStream` is clearly defined in `core` and implemented consistently in `adapters`.
+*   **Error Handling**: Centralize error types in `core/errors.ts` and ensure all adapters use them.
+*   **Constants**: `client/src/api/constants.ts` re-exports from `tauri-constants.ts`. This dependency direction should be verified. If generic constants depend on adapter-specific constants, it might be better to decouple them.

docs/sprints/phase-ongoing/sprint-organization/components.md

@@ -0,0 +1,148 @@
+# Client Components Reorganization Plan
+
+The `client/src/components` directory is currently cluttered with a mix of feature-specific components, layout elements, and shared UI utilities. This document outlines a plan to reorganize them into a structured, scalable hierarchy.
+
+## Analysis
+
+### 1. Common / Shared UI
+**Target Directory**: `client/src/components/common/`
+
+Generic components used across multiple features.
+
+| File | Type | Target | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `empty-state.tsx` | UI | `components/common/empty-state.tsx` | `lucide-react`, `cn` |
+| `stats-card.tsx` | UI | `components/common/stats-card.tsx` | `lucide-react`, `Card` |
+| `error-boundary.tsx` | Logic/UI | `components/common/error-boundary.tsx` | React |
+| `NavLink.tsx` | UI | `components/common/nav-link.tsx` | `react-router-dom` |
+| `icons/status-icons.tsx` | UI | `components/common/icons/status-icons.tsx` | `lucide-react` |
+
+#### Badges & Dialogs
+Sub-groups for common UI patterns.
+
+| File | Type | Target |
+| :--- | :--- | :--- |
+| `annotation-type-badge.tsx` | Badge | `components/common/badges/annotation-type-badge.tsx` |
+| `priority-badge.tsx` | Badge | `components/common/badges/priority-badge.tsx` |
+| `speaker-badge.tsx` | Badge | `components/common/badges/speaker-badge.tsx` |
+| `confirmation-dialog.tsx` | Dialog | `components/common/dialogs/confirmation-dialog.tsx` |
+
+### 2. Layout
+**Target Directory**: `client/src/components/layout/`
+
+Application shell and navigation.
+
+| File | Target | Notes |
+| :--- | :--- | :--- |
+| `app-layout.tsx` | `components/layout/app-layout.tsx` | Main shell |
+| `app-sidebar.tsx` | `components/layout/app-sidebar.tsx` | |
+| `top-bar.tsx` | `components/layout/top-bar.tsx` | |
+
+### 3. Feature Modules
+**Target Directory**: `client/src/components/features/`
+
+Components grouped by business domain.
+
+#### Calendar
+**Target**: `components/features/calendar/`
+| File |
+| :--- |
+| `calendar-connection-panel.tsx` |
+| `calendar-events-panel.tsx` |
+| `upcoming-meetings.tsx` |
+
+#### Connectivity
+**Target**: `components/features/connectivity/`
+| File | Notes |
+| :--- | :--- |
+| `connection-status.tsx` | |
+| `offline-banner.tsx` | |
+| `api-mode-indicator.tsx` | |
+| `server-switch-confirmation-dialog.tsx` | Specific to connection logic |
+
+#### Entities
+**Target**: `components/features/entities/`
+| File |
+| :--- |
+| `entity-highlight.tsx` |
+| `entity-management-panel.tsx` |
+
+#### Integrations
+**Target**: `components/features/integrations/`
+| File | Notes |
+| :--- | :--- |
+| `integration-config-panel.tsx` | Merge with `integration-config-panel/` folder |
+| `webhook-settings-panel.tsx` | |
+
+#### Meetings & Processing
+**Target**: `components/features/meetings/`
+| File |
+| :--- |
+| `meeting-card.tsx` |
+| `meeting-state-badge.tsx` |
+| `processing-status.tsx` |
+
+#### Notes
+**Target**: `components/features/notes/`
+| File |
+| :--- |
+| `timestamped-notes-editor.tsx` |
+
+#### Sync
+**Target**: `components/features/sync/`
+| File |
+| :--- |
+| `sync-control-panel.tsx` |
+| `sync-history-log.tsx` |
+| `sync-status-indicator.tsx` |
+| `preferences-sync-status.tsx` |
+| `preferences-sync-bridge.tsx` |
+
+#### Workspace
+**Target**: `components/features/workspace/`
+| File |
+| :--- |
+| `workspace-switcher.tsx` |
+
+### 4. Existing Features (To Move)
+Move these existing folders into `components/features/`:
+- `analytics` -> `components/features/analytics`
+- `projects` -> `components/features/projects`
+- `recording` -> `components/features/recording`
+- `settings` -> `components/features/settings`
+
+### 5. System / Dev
+**Target Directory**: `client/src/components/system/` (and `dev/`)
+
+| File | Target |
+| :--- | :--- |
+| `tauri-event-listener.tsx` | `components/system/tauri-event-listener.tsx` |
+| `dev-profiler.tsx` | `components/dev/dev-profiler.tsx` |
+| `secure-storage-recovery-dialog.tsx` | `components/system/secure-storage-recovery-dialog.tsx` |
+| `simulation-confirmation-dialog.tsx` | `components/dev/simulation-confirmation-dialog.tsx` |
+
+## Execution Plan
+
+1.  **Preparation**:
+    *   Create new directory structure (`components/features`, `components/common`, `components/layout`, etc.).
+2.  **Move & Rename**:
+    *   Move files to their target destinations.
+    *   Move associated test files (`*.test.tsx`) along with their components.
+3.  **Refactor Imports**:
+    *   Update imports within the moved files (fixing relative paths).
+    *   Update global usage (search and replace imports in `client/src`).
+4.  **Integration Panel Cleanup**:
+    *   Verify `integration-config-panel.tsx` vs `integration-config-panel/` folder. Consolidate into `features/integrations/integration-config-panel/`.
+5.  **Verification**:
+    *   Run build to check for missing imports.
+    *   Run linting.
+    *   Run tests.
+
+## Impacted Areas
+*   **Routing**: Routes in `App.tsx` or `main.tsx` importing pages/layouts.
+*   **Pages**: All page components importing these shared components.
+*   **Tests**: All tests importing these components.
+
+## Recommendations
+*   **Barrel Files**: Add `index.ts` to feature folders (e.g., `components/features/calendar/index.ts`) to simplify imports (e.g., `import { UpcomingMeetings } from '@/components/features/calendar'`).
+*   **Strict Boundaries**: Avoid cross-feature imports where possible. Common logic should move to `hooks` or `lib`.

docs/sprints/phase-ongoing/sprint-organization/hooks.md

@@ -0,0 +1,108 @@
+# Client Hooks Reorganization Plan
+
+The `client/src/hooks` directory is currently a flat list of 40+ files, mixing different domains. This document outlines a plan to reorganize them into domain-specific subdirectories to improve maintainability.
+
+## Analysis
+
+### 1. Audio Hooks
+**Target Directory**: `client/src/hooks/audio/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `use-asr-config.ts` | `useAsrConfig` | `use-asr-config.test.ts` | `getAPI`, `useConnectionState` | `use-asr-config.test.ts` |
+| `use-audio-devices.ts` | `useAudioDevices` | `AudioDeviceSelector`, `Settings`, `AudioTab` | `getAPI`, `useToast`, `useAudioTesting`, `preferences` | `use-audio-devices.test.ts` |
+| `use-audio-testing.ts` | `useAudioTesting` | `useAudioDevices` | `TauriCommands`, `useToast` | N/A (Internal helper) |
+| `use-streaming-config.ts` | `useStreamingConfig` | `AdvancedLocalAiSettings` | `getAPI`, `useConnectionState` | N/A |
+
+### 2. Auth Hooks
+**Target Directory**: `client/src/hooks/auth/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `use-auth-flow.ts` | `useAuthFlow` | **NONE FOUND** (Potential Dead Code) | `getAPI`, `useToast`, `oauth-utils` | N/A |
+| `use-oauth-flow.ts` | `useOAuthFlow` | `IntegrationHandlers`, `CalendarConnectionPanel`, `Settings` | `getAPI`, `useToast`, `oauth-utils` | `use-oauth-flow.test.ts` |
+| `use-oidc-providers.ts` | `useOidcProviders` | `use-oidc-providers.test.ts` | `getAPI`, `useToast` | `use-oidc-providers.test.ts` |
+| `use-cloud-consent.ts` | `useCloudConsent` | `use-cloud-consent.test.ts` | `getAPI` | `use-cloud-consent.test.ts` |
+| `use-huggingface-token.ts` | `useHuggingFaceToken` | `use-huggingface-token.test.ts` | `getAPI`, `useConnectionState` | `use-huggingface-token.test.ts` |
+| `use-secure-integration-secrets.ts` | `useSecureIntegrationSecrets` | `Settings`, `IntegrationHandlers` | `crypto`, `object-utils` | N/A |
+
+### 3. Data Hooks
+**Target Directory**: `client/src/hooks/data/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `use-async-data.ts` | `useAsyncData`, `useMutation` | `use-async-data.ts` | `extractErrorMessage` | N/A |
+| `use-guarded-mutation.ts` | `useGuardedMutation` | `useRecordingSession` | `useConnectionState`, `useToast` | `use-guarded-mutation.test.tsx` |
+| `use-project.ts` | `useProject`, `useActiveProject` | `ProjectMembersPanel` | `useProjects` (context) | N/A |
+| `use-project-members.ts` | `useProjectMembers` | `ProjectMembersPanel` | `getAPI` | N/A |
+
+### 4. Processing Hooks
+**Target Directory**: `client/src/hooks/processing/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `use-post-processing.ts` | `usePostProcessing` | `MeetingDetail`, `ProcessingStatus` | `getAPI`, `useToast`, `entity-store`, `usePostProcessingEvents` | `use-post-processing.test.ts` |
+| `use-entity-extraction.ts` | `useEntityExtraction` | `MeetingDetail` | `getAPI`, `useToast`, `entity-store` | N/A |
+| `use-diarization.ts` | `useDiarization` | `use-diarization.test.ts` | `getAPI`, `useToast` | `use-diarization.test.ts` |
+| `post-processing/` | (Internal Modules) | `usePostProcessing` | N/A | N/A |
+
+### 5. Recording Hooks
+**Target Directory**: `client/src/hooks/recording/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `use-recording-session.ts` | `useRecordingSession` | `RecordingSession.integration.test.tsx` | `getAPI`, `useConnectionState`, `useGuardedMutation`, `useToast` | `recording-session.integration.test.tsx` |
+| `use-recording-app-policy.ts` | `useRecordingAppPolicy` | `RecordingAppPolicySection` | `getAPI`, `preferences` | N/A |
+
+### 6. Sync Hooks
+**Target Directory**: `client/src/hooks/sync/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `use-integration-sync.ts` | `useIntegrationSync` | `use-integration-sync.test.ts` | `getAPI`, `preferences`, `sync-notifications` | `use-integration-sync.test.ts` |
+| `use-integration-validation.ts` | `useIntegrationValidation` | `useIntegrationValidation` | `useToast`, `preferences` | N/A |
+| `use-calendar-sync.ts` | `useCalendarSync` | `Settings`, `CalendarEventsPanel` | `getAPI`, `useToast` | N/A |
+| `use-webhooks.ts` | `useWebhooks` | `WebhookSettingsPanel` | `getAPI`, `useToast` | N/A |
+| `use-preferences-sync.ts` | `usePreferencesSync` | `PreferencesSyncBridge`, `PreferencesSyncStatus` | `preferences-sync`, `preferences` | N/A |
+| `sync-notifications.ts` | `sendSyncNotification` | `useIntegrationSync` | `preferences` | N/A |
+| `use-meeting-reminders.ts` | `useMeetingReminders` | `CalendarEventsPanel` (presumed) | `useToast`, `storage-utils` | N/A |
+
+### 7. UI Hooks
+**Target Directory**: `client/src/hooks/ui/`
+
+| File | Exports | Call Sites | Dependencies | Tests |
+| :--- | :--- | :--- | :--- | :--- |
+| `use-mobile.tsx` | `useIsMobile` | `SidebarContext` | `config` | N/A |
+| `use-panel-preferences.ts` | `usePanelPreferences` | `use-panel-preferences.test.ts` | `storage-utils` | `use-panel-preferences.test.ts` |
+| `use-recording-panels.ts` | `useRecordingPanels` | `Recording` | `react-resizable-panels` | N/A |
+| `use-toast.ts` | `useToast`, `toast` | Widespread | `radix-ui` (implied) | `use-toast.test.ts` |
+
+## Execution Plan
+
+1.  **Create Directories**: `audio`, `auth`, `data`, `processing`, `recording`, `sync`, `ui`.
+2.  **Move Files**: Move source files and associated tests to their new directories.
+3.  **Update Imports**:
+    *   Update relative imports within the moved files.
+    *   Update usages across the codebase (using `sed` or manual edits).
+4.  **Cleanup**: Remove `use-auth-flow.ts` if confirmed as dead code.
+5.  **Verification**: Run tests to ensure no regressions.
+
+## Impacted Tests
+*   `use-asr-config.test.ts`
+*   `use-audio-devices.test.ts`
+*   `use-oauth-flow.test.ts`
+*   `use-oidc-providers.test.ts`
+*   `use-cloud-consent.test.ts`
+*   `use-huggingface-token.test.ts`
+*   `use-guarded-mutation.test.tsx`
+*   `use-post-processing.test.ts`
+*   `use-diarization.test.ts`
+*   `recording-session.integration.test.tsx`
+*   `use-integration-sync.test.ts`
+*   `use-panel-preferences.test.ts`
+*   `use-toast.test.ts`
+
+## Recommendations
+*   **Consolidate Audio**: Consider merging `useAudioTesting` into `useAudioDevices` if it's not used elsewhere.
+*   **Remove Dead Code**: `use-auth-flow.ts` seems redundant given `use-oauth-flow.ts`.
+*   **Standardize Exports**: Ensure all hooks use named exports.

docs/sprints/phase-ongoing/sprint-organization/lib.md

@@ -0,0 +1,148 @@
+# Client Lib Reorganization Plan
+
+The `client/src/lib` directory is currently a flat list of 50+ files mixed with subdirectories, creating a "sloppy" and hard-to-navigate structure. This document outlines a plan to reorganize them into domain-specific subdirectories to improve maintainability and discoverability.
+
+## Analysis
+
+### 1. Audio
+**Target Directory**: `client/src/lib/audio/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `audio-device-ids.ts` | `device-ids.ts` | Device ID resolution logic | None |
+| `audio-device-ids.test.ts` | `device-ids.test.ts` | Tests for device ID resolution | `device-ids` |
+| `audio-device-persistence.integration.test.ts` | `device-persistence.integration.test.ts` | Integration tests for persistence | `storage-keys`, `device-ids` |
+| `speaker-utils.ts` | `speaker.ts` | Speaker stats aggregation | `preferences`, `types` |
+| `speaker-utils.test.ts` | `speaker.test.ts` | Tests for speaker utils | `preferences`, `speaker` |
+
+### 2. Observability
+**Target Directory**: `client/src/lib/observability/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `client-logs.ts` | `client.ts` | Core client logging buffer | `storage-keys`, `types` |
+| `client-logs.test.ts` | `client.test.ts` | Tests for client logging | `client` |
+| `client-log-events.ts` | `events.ts` | Typed log event emitters | `client`, `types` |
+| `client-log-events.test.ts` | `events.test.ts` | Tests for log events | `client`, `events` |
+| `client-log-events.integration.test.ts` | `events.integration.test.ts` | Integration tests | `client`, `events`, `log-messages` |
+| `debug.ts` | `debug.ts` | Dev-mode debug logger | `client` |
+| `error-reporting.ts` | `errors.ts` | Error formatting & toasting | `toast`, `api/helpers` |
+| `log-converters.ts` | `converters.ts` | API to UI log conversion | `types` |
+| `log-converters.test.ts` | `converters.test.ts` | Tests for converters | `converters` |
+| `log-groups.ts` | `groups.ts` | Log grouping logic | `time`, `group-summarizer` |
+| `log-groups.test.ts` | `groups.test.ts` | Tests for grouping | `groups` |
+| `log-group-summarizer.ts` | `group-summarizer.ts` | Summarization logic for groups | `types` |
+| `log-group-summarizer.test.ts` | `group-summarizer.test.ts` | Tests for group summarizer | `group-summarizer` |
+| `log-messages.ts` | `messages.ts` | Human-readable log formatting | None |
+| `log-messages.test.ts` | `messages.test.ts` | Tests for log formatting | `messages` |
+| `log-sanitizer.ts` | `sanitizer.ts` | Sensitive data redaction | None |
+| `log-summarizer.ts` | `summarizer.ts` | Consecutive log summarization | `timing-constants`, `types` |
+| `log-summarizer.test.ts` | `summarizer.test.ts` | Tests for summarizer | `summarizer` |
+
+### 3. Utils (General)
+**Target Directory**: `client/src/lib/utils/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `utils.ts` | `index.ts` | Tailwind `cn` helper | `clsx`, `tailwind-merge` |
+| `utils.test.ts` | `index.test.ts` | Tests for `cn` | `index` |
+| `async-utils.ts` | `async.ts` | Fire-and-forget, AsyncQueue | `client-logs` |
+| `download-utils.ts` | `download.ts` | Blob creation & download | `types` |
+| `event-emitter.ts` | `event-emitter.ts` | Typed event emitter | `client-logs` |
+| `format.ts` | `format.ts` | Date/Time/Number formatting | `time` |
+| `format.test.ts` | `format.test.ts` | Tests for formatting | `format` |
+| `id-utils.ts` | `id.ts` | UUID generation | None |
+| `object-utils.ts` | `object.ts` | Nested object access | None |
+| `object-utils.test.ts` | `object.test.ts` | Tests for object utils | `object` |
+| `polling-utils.ts` | `polling.ts` | Safe polling hooks | React |
+| `time.ts` | `time.ts` | Time constants | None |
+
+### 4. Integrations
+**Target Directory**: `client/src/lib/integrations/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `default-integrations.ts` | `defaults.ts` | Default integration config | `config`, `types` |
+| `integration-utils.ts` | `utils.ts` | Integration helpers & icons | `types`, `lucide-react` |
+| `integration-utils.test.ts` | `utils.test.ts` | Tests for integration utils | `utils` |
+| `oauth-utils.ts` | `oauth.ts` | OAuth state & deep links | `tauri-adapter` |
+
+### 5. Storage
+**Target Directory**: `client/src/lib/storage/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `storage-keys.ts` | `keys.ts` | Centralized storage keys | None |
+| `storage-utils.ts` | `utils.ts` | Safe storage wrappers | `client-logs` |
+| `crypto.ts` | `crypto.ts` | Encrypted storage | `client-logs`, `config`, `storage-keys` |
+| `crypto.test.ts` | `crypto.test.ts` | Tests for crypto | `crypto` |
+
+### 6. Preferences
+**Target Directory**: `client/src/lib/preferences/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `preferences-sync.ts` | `sync.ts` | Sync logic (should move INTO existing dir) | `tauri-api`, `client-logs`, `preferences` |
+| `preferences-sync.test.ts` | `sync.test.ts` | Tests for sync | `sync` |
+| `preferences-validation.test.ts` | `validation.test.ts` | Tests for validation events | `preferences` |
+
+### 7. System
+**Target Directory**: `client/src/lib/system/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `tauri-events.ts` | `events.ts` | Global Tauri event bridge | `tauri-adapter`, `client-logs` |
+| `tauri-events.test.tsx` | `events.test.tsx` | Tests for event bridge | `events` |
+
+### 8. State
+**Target Directory**: `client/src/lib/state/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `entity-store.ts` | `entities.ts` | Global entity store | `api`, `id-utils` |
+| `entity-store.test.ts` | `entities.test.ts` | Tests for entity store | `entities` |
+
+### 9. UI
+**Target Directory**: `client/src/lib/ui/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `styles.ts` | `styles.ts` | Shared Tailwind classes | None |
+| `cva.ts` | `cva.ts` | CVA re-export | `class-variance-authority` |
+| `cva.test.ts` | `cva.test.ts` | Tests for CVA | `cva` |
+
+### 10. Constants
+**Target Directory**: `client/src/lib/constants/`
+
+| File | Proposed Name | Purpose | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `status-constants.ts` | `status.ts` | Status enums (Sync, Connection) | None |
+| `timing-constants.ts` | `timing.ts` | Timing constants | None |
+
+## Execution Plan
+
+1.  **Create Directories**:
+    ```bash
+    mkdir -p client/src/lib/{audio,observability,utils,integrations,storage,system,state,ui,constants}
+    ```
+2.  **Move & Rename Files**: Execute git moves as per the tables above.
+3.  **Cleanup**:
+    *   Delete `client/src/lib/ai-providers.ts` (re-export file) and ensure imports point to `client/src/lib/ai-providers/index`.
+    *   Rename `client/src/lib/ai-providers/` to `client/src/lib/ai/`.
+4.  **Update Imports**:
+    *   Perform search-and-replace for all moved modules.
+    *   Special care for `client-logs`, `storage-keys`, and `utils` (cn) as they are widely used.
+5.  **Verification**:
+    *   Run all tests in `client/src/lib/**`.
+    *   Run type check `npm run type-check`.
+
+## Impacted Areas
+
+*   **Global**: Almost every file in the client application imports from `lib/utils` (cn), `lib/client-logs`, or `lib/storage-keys`.
+*   **Settings**: heavily relies on `preferences` and `integrations`.
+*   **Recording**: relies on `audio`, `observability`, and `system`.
+
+## Recommendations
+
+*   **Barrel Files**: Add `index.ts` to each new subdirectory to simplify imports (e.g., `import { cn } from '@/lib/utils'`).
+*   **Strict Imports**: Enforce imports from the new locations via ESLint if possible.