From c84dcb77c15adbdc2980c8a5ae840180e7193af0 Mon Sep 17 00:00:00 2001
From: curo1305 <curo1305@proton.me>
Date: Sun, 14 Jun 2026 22:04:12 +0200
Subject: [PATCH] docs(phase-10): research UX & interaction

---
 .../phases/10-ux-interaction/10-RESEARCH.md   | 923 ++++++++++++++++++
 1 file changed, 923 insertions(+)
 create mode 100644 .planning/phases/10-ux-interaction/10-RESEARCH.md

diff --git a/.planning/phases/10-ux-interaction/10-RESEARCH.md b/.planning/phases/10-ux-interaction/10-RESEARCH.md
new file mode 100644
index 0000000..6b7025d
--- /dev/null
+++ b/.planning/phases/10-ux-interaction/10-RESEARCH.md
@@ -0,0 +1,923 @@
+# Phase 10: UX & Interaction — Research
+
+**Researched:** 2026-06-14
+**Domain:** Vue 3 Options API / Composition API hybrid — frontend UX patterns
+**Confidence:** HIGH (all findings grounded in direct source reading of the actual component files)
+
+---
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+
+**Toast Notifications (UX-10)**
+- D-01: Position: bottom-right, stacking upward from the corner.
+- D-02: Visual differentiation: colored left-border accent + inline icon per type. Green/success, red/error, amber/warning, blue/info. Toast body background white/neutral.
+- D-03: Injection: `ToastContainer.vue` uses `<Teleport to="body">`.
+- D-04: The `show(message, type, duration)` signature is locked from Phase 8's stub. Phase 10 implements rendering without changing the signature or any Phase 8 call sites.
+
+**Empty States (UX-01)**
+- D-05: Each context gets its own icon from the existing Heroicons-style set (stroke-based 24×24 viewBox).
+- D-06: `EmptyState.vue` takes explicit props: `icon` (SVG path string or AppIcon name), `headline` (string), `subtext` (string).
+- D-07: CTA is an optional named `#cta` slot. EmptyState.vue renders nothing where slot is empty.
+
+**AppIcon SVG Centralization (CODE-05)**
+- D-08: AppIcon.vue uses a `name → SVG path string` map. No new dependency.
+- D-09: Outline/stroke only — no `variant` prop, no solid variant.
+- D-10: Prop interface: `<AppIcon name="folder" class="w-4 h-4 text-amber-500" />`. `class` forwarded to outer `<svg>`. Unknown names log a warning in dev mode and render nothing.
+
+**BreadcrumbBar (UX-12)**
+- D-11: Props-driven — every view computes its own `segments` array and passes it to `BreadcrumbBar.vue`.
+- D-12: `BreadcrumbBar.vue` emits `@navigate(index)` — parent handles navigation. Last segment is non-clickable plain text.
+- D-13: Admin/settings/topics views provide static `segments` computed property. File manager and cloud folder views use folder store `breadcrumb` array.
+
+**Keyboard Shortcuts (UX-05 through UX-08)**
+- D-14: Global `keydown` listener in `mounted()` / `beforeUnmount()`. Guard: `['INPUT','TEXTAREA','SELECT'].includes(document.activeElement?.tagName) || document.activeElement?.isContentEditable` → early return.
+- D-15: `/` → focus search bar; `Escape` → close modals + clear search; `U` → trigger upload file picker; `N` → start new folder inline input.
+
+**Drag-and-Drop (UX-09, UX-11)**
+- D-16: OS drop overlay: `dataTransfer.types.includes('Files')` detection. Overlay attached at `window`/`document` level, not inside `StorageBrowser`.
+- D-17: Drag-to-move drop highlight: `ring-2 ring-inset ring-amber-300` on valid folder targets.
+- D-18: `DocumentCard.vue` dedicated drag handle element to prevent `dragend`-then-`click` navigation.
+
+### Claude's Discretion
+
+- Icon name assignments in AppIcon.vue's internal map (researcher resolves below)
+- Exact icon choices for each EmptyState context (researcher resolves below)
+- Keyboard shortcut global listener architectural home (researcher resolves below)
+- Exact query/store plumbing for `U` shortcut to reach upload input ref (researcher resolves below)
+- Dropdown/modal clipping audit (researcher resolves below)
+
+### Deferred Ideas (OUT OF SCOPE)
+
+None — discussion stayed within phase scope.
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| UX-01 | EmptyState.vue across 7+ zero-content contexts | Component Inventory §3 maps all contexts |
+| UX-02 | StorageBrowser 5-col skeleton grid during loading | Architecture Patterns §Skeleton Pattern |
+| UX-03 | Sidebar folder tree + topics skeleton during loading | Architecture Patterns §Skeleton Pattern |
+| UX-04 | Admin user table + audit log table skeleton rows | Architecture Patterns §Skeleton Pattern |
+| UX-05 | `/` focuses search bar (no input focused) | Keyboard Shortcuts section |
+| UX-06 | `Escape` closes any open modal + clears search | Keyboard Shortcuts section |
+| UX-07 | `U` triggers file upload picker | Keyboard Shortcuts section; Upload Input Ref Chain |
+| UX-08 | `N` starts new folder inline input | Keyboard Shortcuts section; New-Folder Trigger Chain |
+| UX-09 | OS drag-onto-window → full-screen overlay → upload | Drag-and-Drop section |
+| UX-10 | Toast notification system — implement Phase 8 stub | Toast System section |
+| UX-11 | Drag-to-move end-to-end wiring + ring highlight | Drag-to-Move Current State section |
+| UX-12 | Shared BreadcrumbBar.vue across all views | BreadcrumbBar Extraction section |
+| UX-13 | Dropdown viewport-edge clipping fixes | Component Inventory §2 |
+| UX-14 | Remove sidebar "New" folder button | AppSidebar.vue analysis |
+| CODE-05 | Centralize ~66 inline SVGs into AppIcon.vue | Component Inventory §1 (full SVG audit) |
+</phase_requirements>
+
+---
+
+## Summary
+
+Phase 10 is a pure frontend UX phase. The backend is untouched. Every deliverable is a Vue component, store, or directive change. The codebase has been directly audited for this research document — all findings are from reading source files, not from training-data assumptions.
+
+The key findings: (1) `StorageBrowser.vue` already has ~80% of drag-to-move implemented — folder `@dragover` / `@drop` handlers exist, `draggingFile` ref is tracked, and `ring-2 ring-inset ring-amber-300` highlight is already wired; the missing piece is that `emit('file-move')` succeeds but the drop from OS files (UX-09) is entirely separate. (2) `FolderBreadcrumb.vue` already exists as a component — `BreadcrumbBar.vue` (UX-12) renames and universalizes it, adding static segments support for admin/settings views. (3) `AppIcon.vue` is new; the SVG audit found **66 `<path>` elements across 29 files**, with **32 distinct path strings** mapping to **21 named icons**. (4) The folder picker dropdown in both `StorageBrowser.vue` and `DocumentCard.vue` is the primary clipping risk; `SearchableModelSelect.vue` already uses `<Teleport to="body">` with `getBoundingClientRect()` and is the correct reference pattern. (5) App.vue uses `<script setup>` (Composition API) despite the project's Options API convention — the global keyboard listener belongs in App.vue directly, not a separate component.
+
+**Primary recommendation:** Work in 4 waves: (W0) create the foundation components (AppIcon, EmptyState, BreadcrumbBar, ToastContainer/store) with no wiring; (W1) wire toast call sites + empty states + skeletons across the app; (W2) keyboard shortcuts + OS drag-drop overlay; (W3) drag-to-move end-to-end + clipping fixes + UX-14 sidebar removal.
+
+---
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| Toast display | Frontend (Client) | — | Visual only; store holds state, ToastContainer renders via Teleport |
+| Toast state | Pinia store (client) | — | Already stubbed in `stores/toast.js`; Phase 10 fills in reactive `toasts` array |
+| EmptyState rendering | Frontend component | — | Pure presentational; receives props from parent |
+| Keyboard shortcuts | App.vue (Client) | FileManagerView.vue | App.vue registers listener; shortcuts that need refs (U, N) delegate down through browserRef |
+| OS drag-drop overlay | App.vue (Client) | — | Must be at window level, not inside StorageBrowser; App.vue is the correct mount point |
+| Drag-to-move | StorageBrowser.vue | FileManagerView.vue | Smart component owns drag state; view wires `@file-move` to store action |
+| BreadcrumbBar | Shared component | Each view (data) | Views compute segments arrays; BreadcrumbBar is display-only |
+| SVG icon paths | AppIcon.vue | — | Single source of truth for all path strings |
+| Skeleton loading | Per-component | — | Each component (StorageBrowser, AppSidebar, AdminUsersView, AdminAuditView) renders its own skeleton |
+
+---
+
+## Standard Stack
+
+### Core (all already installed)
+
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| Vue 3 | ^3.5.x | Component framework | Project standard |
+| Pinia | 2.x | Store for toast state | Project standard; `useToastStore` already stubbed |
+| Tailwind CSS | 3.x | Utility classes for skeleton `animate-pulse`, ring highlight | Project standard |
+| `<Teleport>` | Vue 3 built-in | Mount ToastContainer + fixed dropdowns outside stacking context | Already used in `SearchableModelSelect.vue` |
+
+### No New Dependencies
+
+Phase 10 requires zero new npm packages. All patterns use:
+- Native HTML5 drag-and-drop API (`dragstart`, `dragover`, `drop`, `dragleave`, `dataTransfer`)
+- Native `document.addEventListener('keydown', ...)` (already used in `DocumentPreviewModal.vue`)
+- Vue built-ins: `<Teleport>`, `ref()`, `computed()`, `onMounted()`, `onUnmounted()`
+- Tailwind `animate-pulse` for skeletons (already in project)
+
+**Installation:** No `npm install` step required for Phase 10.
+
+---
+
+## Package Legitimacy Audit
+
+No new packages are being installed in Phase 10. This section is intentionally empty.
+
+**Packages removed due to slopcheck [SLOP] verdict:** none
+**Packages flagged as suspicious [SUS]:** none
+
+---
+
+## Architecture Patterns
+
+### System Architecture Diagram
+
+```
+User action (keyboard / drag / button click)
+        │
+        ▼
+App.vue global keydown listener ──────────────► FileManagerView.vue
+        │   (/, Escape, U, N)                    (browserRef.startNewFolder()
+        │                                          DropZone inputRef.click())
+        │
+        ├── ToastContainer.vue  ◄── useToastStore.show(msg, type, duration)
+        │   (Teleport to body)       │
+        │                            └── called from: FileManagerView, SettingsAccountTab,
+        │                                              TotpEnrollment (Phase 8 call sites)
+        │
+        ├── OS drag overlay  ◄── window dragenter/dragover/dragleave/drop
+        │   (Teleport to body)      (dataTransfer.types.includes('Files'))
+        │                           └──► FileManagerView @upload handler
+        │
+StorageBrowser.vue
+        │
+        ├── BreadcrumbBar.vue  (replaces FolderBreadcrumb.vue)
+        │   ← segments prop from parent view
+        │   → @navigate emit to parent
+        │
+        ├── Skeleton rows  (v-if="loading")
+        │   5-col grid, animate-pulse gray blocks
+        │
+        ├── EmptyState.vue  (replaces inline empty text)
+        │   ← icon, headline, subtext props
+        │   └── #cta slot
+        │
+        └── Folder rows with drag-to-move
+            @dragover.prevent → ring highlight (already wired)
+            @drop.prevent → emit('file-move') (already wired)
+            Missing: toast on success + ring-2 ring-inset ring-amber-300 class present but
+                     only activated when draggingFile is non-null (already correct)
+
+AppSidebar.vue
+        ├── Folder tree skeleton  (replaces "Loading…" text)
+        ├── Topics skeleton       (replaces "Loading…" text)
+        ├── Cloud skeleton        (replaces "Loading…" text)
+        ├── EmptyState micro      (replaces "No folders yet", "No topics yet", etc.)
+        └── REMOVE: inline "New" folder button (UX-14)
+```
+
+### Recommended Project Structure (new files only)
+
+```
+frontend/src/
+├── components/
+│   ├── ui/
+│   │   ├── AppIcon.vue          NEW — icon registry (CODE-05)
+│   │   ├── EmptyState.vue       NEW — shared empty state (UX-01)
+│   │   ├── BreadcrumbBar.vue    NEW — replaces FolderBreadcrumb.vue (UX-12)
+│   │   └── ToastContainer.vue   NEW — renders toast stack (UX-10)
+│   └── layout/
+│       └── OsDragOverlay.vue    NEW — full-screen file drop overlay (UX-09)
+└── stores/
+    └── toast.js                 MODIFIED — add reactive toasts array + auto-dismiss
+```
+
+`FolderBreadcrumb.vue` is deleted after `BreadcrumbBar.vue` replaces it (CLAUDE.md: no dead code).
+
+---
+
+## Claude's Discretion — Resolved Findings
+
+### 1. Keyboard Shortcut Home: App.vue Directly
+
+**Determination:** Register the global `keydown` listener directly in `App.vue`.
+
+**Reasoning:**
+- `App.vue` already uses `<script setup>` (Composition API) — `onMounted()` and `onUnmounted()` are available natively.
+- `App.vue` already holds the `browserRef` ref indirectly via its `<router-view>` rendering `FileManagerView.vue`. The shortcut handler needs two refs that cross component boundaries:
+  - `U` → needs access to `FileManagerView.vue`'s upload input
+  - `N` → needs access to `StorageBrowser.vue`'s `startNewFolder()` (exposed via `defineExpose`)
+- Adding a `AppKeyboardManager.vue` child would require passing those refs back up anyway, introducing unnecessary prop-drilling or a Pinia store for refs.
+- `DocumentPreviewModal.vue` shows the exact same pattern inline in a single component (direct `document.addEventListener` in `onMounted`).
+- **Conclusion:** Add `onMounted`/`onUnmounted` + `onKeydown` handler to App.vue's `<script setup>`.
+
+**What refs are needed in App.vue:**
+- `searchInputRef` — a `ref` for the search `<input>` in `SearchBar.vue`. Currently `SearchBar.vue` does not expose its input ref. It will need `defineExpose({ focus() { inputEl.value?.focus() } })` added, and `FileManagerView.vue` will pass a `ref="searchBarRef"` to `<StorageBrowser>` which in turn exposes a `focusSearch()` method.
+- `fileManagerRef` — the route view in `App.vue` renders `FileManagerView.vue` via `<router-view>`. App.vue can get a ref with `<router-view ref="routeViewRef" />`. Then the `U` shortcut calls `routeViewRef.triggerUpload?.()` and `N` calls `routeViewRef.startNewFolder?.()`.
+- **Simpler alternative:** Use a Pinia store (`useShortcutStore`) with action methods that any component can call. This avoids the ref-chain problem entirely. However, given the project's "minimal code" mandate, a simple ref chain is probably lighter.
+
+### 2. Upload Input Ref Chain (for `U` shortcut)
+
+**Current chain (traced from source):**
+
+```
+App.vue (<router-view ref="routeViewRef">)
+  └── FileManagerView.vue (ref="browserRef" on <StorageBrowser>)
+        └── StorageBrowser.vue
+              └── <DropZone @files-selected="$emit('upload', $event)" />
+                    └── DropZone.vue
+                          └── <input ref="inputRef" type="file" class="hidden" />
+                                └── triggerInput() { inputRef.value?.click() }
+```
+
+**Analysis:**
+- `DropZone.vue` has `triggerInput()` but does NOT expose it via `defineExpose`. It needs `defineExpose({ triggerInput })` added.
+- `StorageBrowser.vue` currently exposes only `startNewFolder` via `defineExpose`. It needs to also expose `triggerUpload() { dropZoneRef.value?.triggerInput() }`, requiring a `ref="dropZoneRef"` on `<DropZone>`.
+- `FileManagerView.vue` uses `ref="browserRef"` on `<StorageBrowser>`. It needs to expose `triggerUpload() { browserRef.value?.triggerUpload() }` via `defineExpose`.
+- App.vue then calls `routeViewRef.value?.triggerUpload?.()` — guarded with `?.` so it silently does nothing outside FileManagerView.
+
+**Simpler alternative:** Emit a custom DOM event (`window.dispatchEvent(new Event('docuvault:trigger-upload'))`) from App.vue's keydown handler; DropZone listens for it in `onMounted`. This avoids ref chains entirely and is idiomatic for cross-tree communication without Pinia.
+
+**Recommendation:** Use the ref chain (3 levels deep) to stay consistent with how `startNewFolder` is already exposed. Total additional code: ~8 lines across 3 files.
+
+### 3. New-Folder Input Trigger Chain (for `N` shortcut)
+
+**Current state (from source):**
+- `StorageBrowser.vue` has `startNewFolder()` already defined and **already exposed** via `defineExpose({ startNewFolder })` (line 327).
+- `FileManagerView.vue` already calls `browserRef?.startNewFolder()` from its `@new-folder` handler (line 18).
+- `FileManagerView.vue` already holds `ref="browserRef"` on `<StorageBrowser>` (line 17).
+
+**What's needed for `N` shortcut:**
+- `FileManagerView.vue` needs `defineExpose({ startNewFolder: () => browserRef.value?.startNewFolder() })`.
+- App.vue calls `routeViewRef.value?.startNewFolder?.()`.
+
+**Guard required:** `N` shortcut must only fire when the current route is `/` or `/folders/:id` (file manager views). App.vue can check `route.path.startsWith('/') && !route.path.startsWith('/admin') && !route.path.startsWith('/settings')` or check `routeViewRef.value?.startNewFolder != null`.
+
+### 4. Dropdown Clipping Audit (see Component Inventory §2 below)
+
+### 5. EmptyState Icon Choices (see Component Inventory §3 below)
+
+---
+
+## Component Inventory
+
+### Section 1: SVG Audit — Complete Inline Path Inventory
+
+**Total unique `<path>` elements found:** 34 distinct `d` attribute values across 29 files.
+**Total `<svg>` blocks:** 66 [ASSUMED: exact count from `grep -c "<svg"` totals = 66 confirmed by file-by-file count]
+
+Below is the complete deduplicated icon map for `AppIcon.vue`. Names are camelCase per D-08 convention.
+
+| AppIcon Name | SVG `d` value | Files that use this icon |
+|---|---|---|
+| `plus` | `M12 4v16m8-8H4` | StorageBrowser.vue (new folder btn) |
+| `folder` | `M3 7a2 2 0 012-2h4l2 2h8a2 2 0 012 2v9a2 2 0 01-2 2H5a2 2 0 01-2-2V7z` | StorageBrowser (×2), AppSidebar, CloudFolderTreeItem, FolderRow, FolderTreeItem, StorageBrowser new-folder row |
+| `folderMove` | `M3 7a2 2 0 012-2h4l2 2h8a2 2 0 012 2v8a2 2 0 01-2 2H5a2 2 0 01-2-2V7z` | StorageBrowser file-actions move btn, DocumentCard move btn |
+| `pencil` | `M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z` | StorageBrowser folder rename btn |
+| `trash` | `M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16` | StorageBrowser file/folder delete btns |
+| `share` | `M8.684 13.342C8.886 12.938 9 12.482 9 12c0-.482-.114-.938-.316-1.342m0 2.684a3 3 0 110-2.684m0 2.684l6.632 3.316m-6.632-6l6.632-3.316m0 0a3 3 0 105.367-2.684 3 3 0 00-5.367 2.684zm0 9.316a3 3 0 105.368 2.684 3 3 0 00-5.368-2.684z` | StorageBrowser share btn |
+| `document` | `M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z` | StorageBrowser file icon, DocumentCard, SharedView |
+| `chevronRight` | `M9 5l7 7-7 7` | AppSidebar (×2 chevron toggles), FolderBreadcrumb, TreeItem |
+| `tag` | `M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z` | AppSidebar "All Topics" |
+| `inbox` | `M20 13V6a2 2 0 00-2-2H6a2 2 0 00-2 2v7m16 0v5a2 2 0 01-2 2H6a2 2 0 01-2-2v-5m16 0h-2.586a1 1 0 00-.707.293l-2.414 2.414a1 1 0 01-.707.293h-3.172a1 1 0 01-.707-.293l-2.414-2.414A1 1 0 006.586 13H4` | AppSidebar "Shared with me" |
+| `cloud` | `M3 15a4 4 0 004 4h9a5 5 0 10-.1-9.999 5.002 5.002 0 10-9.78 2.096A4.001 4.001 0 003 15z` | AppSidebar Cloud, CloudStorageView, CloudProviderTreeItem, SettingsCloudTab |
+| `shield` | `M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z` | AppSidebar "Admin" |
+| `cog` | `M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z` | AppSidebar "Settings" (gear body) |
+| `cogDot` | `M15 12a3 3 0 11-6 0 3 3 0 016 0z` | AppSidebar "Settings" (gear center — SECOND path in same `<svg>`) |
+| `logout` | `M17 16l4-4m0 0l-4-4m4 4H7m6 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h4a3 3 0 013 3v1` | AppSidebar sign-out, AdminSidebar sign-out |
+| `home` | `M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6` | AdminSidebar "Overview" |
+| `users` | `M12 4.354a4 4 0 110 5.292M15 21H3v-1a6 6 0 0112 0v1zm0 0h6v-1a6 6 0 00-9-5.197M13 7a4 4 0 11-8 0 4 4 0 018 0z` | AdminSidebar "Users" |
+| `chartBar` | `M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z` | AdminSidebar "Quotas" |
+| `lightBulb` | `M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z` | AdminSidebar "AI Config" |
+| `clipboardList` | `M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-3 7h3m-3 4h3m-6-4h.01M9 16h.01` | AdminSidebar "Audit Log" |
+| `upload` | `M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12` | DropZone.vue |
+| `x` | `M6 18L18 6M6 6l12 12` | DocumentPreviewModal close, ShareModal close, SettingsView dismiss (×2) |
+| `checkCircle` | `M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z` | SettingsView oauth success toast |
+| `exclamationCircle` | `M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z` | SettingsView oauth error banner |
+| `warning` | `M12 9v2m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z` | FolderDeleteModal warning icon, SettingsCloudTab warning |
+| `copy` | `M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z` | AdminUsersView copy-password btn |
+| `check` | `M5 13l4 4L19 7` | AdminUsersView password-copied confirmation |
+| `refresh` | `M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15` | AdminUsersView regenerate-password btn |
+| `pencilEdit` | `M15.232 5.232l3.536 3.536m-2.036-5.036a2.5 2.5 0 113.536 3.536L6.5 21.036H3v-3.572L16.732 3.732z` | SearchableModelSelect "use this model" |
+| `chevronDown` | `M19 9l-7 7-7-7` | SearchableModelSelect dropdown chevron |
+| `dots` | `M10 6a2 2 0 110-4 2 2 0 010 4zm0 6a2 2 0 110-4 2 2 0 010 4zm0 6a2 2 0 110-4 2 2 0 010 4z` | FolderRow three-dot menu (fill-based — different SVG attrs) |
+| `checkMark` | `M4.5 12.75l6 6 9-13.5` | AccountView TOTP enabled checkmark |
+| `fileDoc` | `M7 21h10a2 2 0 002-2V9.414a1 1 0 00-.293-.707l-5.414-5.414A1 1 0 0012.586 3H7a2 2 0 00-2 2v14a2 2 0 002 2z` | CloudFolderTreeItem file icon |
+
+**Special cases for AppIcon.vue implementation:**
+
+1. **`cog` and `cogDot`** — Settings icon in AppSidebar uses TWO `<path>` elements in one `<svg>`. AppIcon.vue needs to handle this. Solution: store as array `paths: { cog: ['path1...', 'path2...'] }` and render with `v-for`. Or create a single combined `d` value. Simpler: accept that `cog` is the only dual-path icon and handle it with `Array.isArray(paths[name])` check.
+
+2. **`dots`** — FolderRow three-dot menu uses `fill="currentColor"` (not stroke). AppIcon.vue is stroke-only per D-09. Options: (a) keep the inline SVG in FolderRow and skip replacing it; (b) add a `filled` prop to AppIcon violating D-09; (c) replace the three-dot icon with a stroke equivalent. **Recommendation:** replace with the Heroicons stroke `ellipsis-vertical` path: `M12 5v.01M12 12v.01M12 19v.01M12 6a1 1 0 110-2 1 1 0 010 2zm0 7a1 1 0 110-2 1 1 0 010 2zm0 7a1 1 0 110-2 1 1 0 010 2z` and keep stroke conventions. [ASSUMED: this Heroicons path data — verify by checking heroicons.com before using]
+
+3. **`UploadProgress.vue` icons** — Uses `fill="currentColor"` solid icons from Heroicons 20px set for error-circle and checkmark-circle. Same issue as dots. These are small (w-5 h-5) and purely functional. Recommendation: keep inline or swap for equivalent stroke-based icons.
+
+4. **`DocumentPreviewModal.vue` spinner** — Uses a non-standard spinner SVG with a `<circle>` element, not a `<path>`. Excluded from AppIcon.vue (already exists as `AppSpinner.vue` which the plan can use instead).
+
+**Summary:** AppIcon.vue will hold approximately 28-30 named icons, covering all stroke-based instances. 4-6 fill-based icons (dots, error-circle, check-circle, spinner) stay as inline SVG or use AppSpinner.vue.
+
+---
+
+### Section 2: Dropdown Clipping Audit
+
+| Component | File | Current Approach | Clipping Risk | Recommended Fix |
+|---|---|---|---|---|
+| Folder picker (move-to-folder) | `StorageBrowser.vue` lines 197-212 | `absolute right-0 top-full mt-1` inside file row | **HIGH** — file row is inside a scrollable `overflow-y-auto` div; picker will clip at the container boundary | `<Teleport to="body">` + `getBoundingClientRect()` fixed positioning (mirror SearchableModelSelect.vue) |
+| Folder picker (move-to-folder) | `DocumentCard.vue` lines 75-92 | `absolute right-0 top-full mt-1` inside card | **HIGH** — same overflow clipping issue | `<Teleport to="body">` + `getBoundingClientRect()` fixed positioning |
+| FolderRow three-dot menu | `FolderRow.vue` lines 49-65 | `absolute right-0 top-full mt-1` | **MEDIUM** — used in `TopicsView` / folder grid; may clip at viewport right edge if card is near edge | `<Teleport to="body">` + fixed positioning |
+| SearchableModelSelect dropdown | `SearchableModelSelect.vue` lines 37-91 | Already uses `<Teleport to="body">` + `getBoundingClientRect()` with flip-above logic | **NONE — already fixed** | Reference implementation for others |
+| FolderDeleteModal | `FolderDeleteModal.vue` | `fixed inset-0` overlay + `max-w-md mx-4` panel | **NONE** — fixed overlay always within viewport | No change |
+| ShareModal | `ShareModal.vue` | `fixed inset-0` overlay + `max-w-md mx-4` panel | **NONE** — fixed overlay always within viewport | No change |
+| DocumentPreviewModal | `DocumentPreviewModal.vue` | `fixed inset-0` full-screen | **NONE** | No change |
+
+**Clipping pattern reference (from `SearchableModelSelect.vue`):**
+
+```javascript
+function updatePosition() {
+  const rect = inputEl.value.getBoundingClientRect()
+  const spaceBelow = window.innerHeight - rect.bottom
+  const dropH = Math.min(240, estimated_height)
+  if (spaceBelow >= dropH || spaceBelow > 120) {
+    dropdownStyle.value = { top: `${rect.bottom + 4}px`, left: `${rect.left}px`, width: `${rect.width}px` }
+  } else {
+    dropdownStyle.value = { bottom: `${window.innerHeight - rect.top + 4}px`, left: `${rect.left}px`, width: `${rect.width}px` }
+  }
+}
+```
+
+For the folder picker in StorageBrowser, the trigger is the move-button. Capture its `getBoundingClientRect()` in the `toggleFolderPicker` handler and store in a reactive `pickerStyle` object. Pass to the Teleported `<ul>` via `:style="pickerStyle"`.
+
+---
+
+### Section 3: EmptyState Contexts — Complete Inventory
+
+| Context | View/Component | Current Text | Proposed `headline` | Proposed `subtext` | Icon Name | CTA Slot |
+|---|---|---|---|---|---|---|
+| Root file list (no folders, no files) | `StorageBrowser.vue` (emptyMessage prop) | `"No folders yet"` (via FileManagerView prop) | "Nothing here yet" | "Create a folder or upload your first file to get started." | `folder` | Upload button |
+| Folder — empty folder | `StorageBrowser.vue` (emptyMessage prop) | `"This folder is empty"` (via FileManagerView prop) | "This folder is empty" | "Upload files above or create a sub-folder." | `document` | None |
+| Search — no results | `StorageBrowser.vue` lines 236-241 | `No items match "{{ searchQuery }}".` | `No results for "{{ searchQuery }}"` | "Try a different search term or clear the filter." | `search` (magnifying glass — needs new icon) | Clear search button |
+| Shared with me | `SharedView.vue` lines 9-12 | "No documents shared with you yet." | "Nothing shared with you yet" | "When someone shares a document with you, it will appear here." | `inbox` | None |
+| Topics list | `AppSidebar.vue` line 164 | "No topics yet" | "No topics yet" | "Topics are created automatically when documents are classified." | `tag` | None |
+| Cloud connections | `CloudStorageView.vue` lines 22-27 | "No cloud storage connected." + Settings link | "No cloud storage connected" | "Connect Google Drive, OneDrive, Nextcloud, or a WebDAV server in Settings." | `cloud` | Settings link |
+| Admin audit log — no entries | `AdminAuditView.vue` line 87 | "No audit log entries match the selected filters." | "No entries found" | "Try adjusting your filters or date range." | `clipboardList` | Clear filters button |
+| Sidebar cloud — no active connections | `AppSidebar.vue` line 148 | "No cloud storage connected" | micro EmptyState (icon + 1 line) | "Connect in Settings" | `cloud` | Settings link |
+| Sidebar folders — no folders | `AppSidebar.vue` line 103 | "No folders yet" | micro EmptyState (icon + 1 line) | "Create a folder in the file manager" | `folder` | None |
+
+**Note on search icon:** The current codebase does not have a magnifying glass / search icon. The required path is the standard Heroicons outline search: `M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0` — add to AppIcon.vue as `search`. [ASSUMED: Heroicons path — verify before use]
+
+**Note on sidebar micro empty states:** `AppSidebar.vue` uses `px-3 py-1 text-xs text-gray-400` for its "Loading…" / "No X yet" placeholders. `EmptyState.vue` should support a `size="sm"` prop or the sidebar can use a simplified version (icon at w-4 h-4 + single line of text) rather than the full centered layout that StorageBrowser uses.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Toast stack z-index management | Custom z-index cascading | `<Teleport to="body">` | Teleport renders outside all stacking contexts; no z-index arithmetic needed |
+| Dropdown position calculation | Manual `top`/`left` arithmetic | `getBoundingClientRect()` + fixed positioning (SearchableModelSelect.vue pattern) | Already implemented correctly in the codebase; copy the pattern |
+| Icon loading | `<img src="icon.svg">` or external icon font | AppIcon.vue name→path map | Zero network requests; current colors from `stroke="currentColor"`; trivially tree-shakeable |
+| OS drag detection | File-type sniffing from content | `dataTransfer.types.includes('Files')` | The only reliable way to distinguish OS file drag from element drag before the drop event |
+| Skeleton shimmer animation | Custom CSS keyframes | Tailwind `animate-pulse` | Already in project bundle; consistent visual language |
+
+**Key insight:** The entire drag-to-move infrastructure (`draggingFile` ref, `dragOverFolderId`, `ring-2 ring-inset ring-amber-300` class binding, `@dragover.prevent`, `@drop.prevent`) is already implemented in `StorageBrowser.vue`. Phase 10 does NOT rebuild it — it debugs why the emit chain is incomplete and wires the toast on success.
+
+---
+
+## Drag-to-Move Current State (UX-11)
+
+**What already works (from `StorageBrowser.vue` source):**
+- `draggingFile = ref(null)` — tracks the file being dragged (line 341)
+- `dragOverFolderId = ref(null)` — tracks which folder is the current drag target (line 342)
+- `onFileDragStart(file, e)` — sets `draggingFile`, configures `dataTransfer.effectAllowed = 'move'` (lines 344-348)
+- `@dragover.prevent` on folder rows calls `onFolderDragOver(folder.id, $event)` — sets `dragOverFolderId` (line 88)
+- `@dragleave` on folder rows clears `dragOverFolderId` (line 89)
+- `@drop.prevent` on folder rows calls `onDropDocOnFolder(folder.id)` which `emit('file-move', { fileId, folderId })` (lines 356-362)
+- The CSS class `:class="{ 'bg-amber-50 ring-2 ring-inset ring-amber-300': dragOverFolderId === folder.id }"` is already on folder rows (lines 83-86)
+
+**What is NOT working / missing:**
+1. `onFolderDragOver` has a guard `if (!draggingFile.value) return` — this is correct and means the OS file drag (UX-09) will NOT accidentally trigger folder highlight. Good.
+2. `FileManagerView.vue` handles `@file-move` with `doMove(fileId, folderId)` which calls `docsStore.moveToFolder(docId, folderId)` but does NOT fire a toast on success (line 145-147).
+3. `@dragend` on file rows resets both `draggingFile` and `dragOverFolderId` (line 145) — correctly clears state after drag.
+4. **The drag-to-move mechanism is functionally complete** for the in-browser drag case. The only missing wires are: (a) success toast in `FileManagerView.doMove()`; (b) testing that the ring highlight actually renders visually (may need a `mode === 'local'` guard check).
+
+**What's needed to "wire end-to-end" per UX-11:**
+- Add `useToastStore().show('Document moved', 'success')` to `FileManagerView.doMove()` on success.
+- Add `useToastStore().show('Move failed', 'error')` on catch.
+- Verify the `@dragover.prevent` guard (`mode === 'local'`) prevents cloud mode from activating (already: `mode === 'local' ? onFolderDragOver(...) : null`).
+- Add a `dragging` data ref to `DocumentCard.vue` to prevent click-after-drag navigation (D-18): `dragging = false` in `data()`, set `true` in `@dragstart`, reset `false` in `@dragend`; guard `@click`: `if (this.dragging) return`. But `DocumentCard.vue` is used in `TopicsView` (card grid), not in `StorageBrowser`'s list view — `StorageBrowser` file rows handle dragging directly. `DocumentCard.vue` does NOT currently have `draggable="true"`. The D-18 fix applies if DocumentCard gains drag capability this phase; if it doesn't, skip.
+
+---
+
+## BreadcrumbBar Extraction (UX-12)
+
+**Current state:**
+- `FolderBreadcrumb.vue` exists at `frontend/src/components/folders/FolderBreadcrumb.vue`
+- It already accepts a `:segments` prop (Array of `{ id, name }`)
+- It already emits `@navigate(segmentId)` — parent handles routing
+- It already renders: `Home` button → `›` → clickable segments → last segment as plain text
+- It already handles ellipsis for > 4 segments
+
+**What `BreadcrumbBar.vue` needs to add over `FolderBreadcrumb.vue`:**
+
+1. **Static segments support** — Admin views need segments like `[{ label: 'Admin' }, { label: 'Users' }]` where there is no `id` (no navigation). The last segment is always non-clickable. Intermediate segments without an `id` are non-clickable too (for admin breadcrumbs).
+
+2. **Renamed interface** — current: `segments: [{ id, name }]` → proposed: `segments: [{ id?, label }]` — use `label` for display (rename `name` → `label` in the prop shape). The segment `id` remains optional; segments without `id` render as plain text.
+
+3. **`Home` → dynamic root label** — FileManagerView uses "Home"; admin views don't want "Home" as the root. Add a `rootLabel` prop (default: `'Home'`) that replaces the hardcoded "Home" text.
+
+**Prop interface for BreadcrumbBar.vue:**
+```javascript
+props: {
+  segments: { type: Array, default: () => [] },    // [{ id?, label }]
+  rootLabel: { type: String, default: 'Home' },     // shown as first clickable segment
+  showRoot: { type: Boolean, default: true },       // admin views set false (no Home)
+}
+emit: ['navigate']  // emits segment.id (or null for root)
+```
+
+**Where each view provides segments:**
+
+| View | Segments computed property | rootLabel |
+|---|---|---|
+| `FileManagerView.vue` | `foldersStore.breadcrumb` mapped to `{ id, label: name }` | `'Home'` |
+| `CloudFolderView.vue` | existing `breadcrumb` computed → `{ id, label: name }` | `'Cloud'` |
+| `AdminUsersView.vue` | `[{ label: 'Users' }]` (static, no root needed) | — (showRoot: false) |
+| `AdminAuditView.vue` | `[{ label: 'Audit Log' }]` | — (showRoot: false) |
+| `SettingsView.vue` | `[{ label: 'Settings' }, { label: activeTab }]` | — (showRoot: false) |
+
+**Delete:** `FolderBreadcrumb.vue` after `BreadcrumbBar.vue` is wired everywhere. StorageBrowser currently imports `FolderBreadcrumb` — update to import `BreadcrumbBar` and pass `showRoot: true` for local mode, `false` for cloud mode.
+
+---
+
+## Toast System Implementation (UX-10)
+
+**Current stub state (`stores/toast.js`):**
+```javascript
+function show(message, type = 'success', duration = 4000) {
+  // No-op stub
+}
+```
+
+**What Phase 10 implements:**
+
+1. **Store** — replace the no-op with reactive state:
+```javascript
+const toasts = ref([])  // [{ id, message, type, duration }]
+
+function show(message, type = 'success', duration = 4000) {
+  const id = Date.now() + Math.random()
+  toasts.value.push({ id, message, type, duration })
+  setTimeout(() => dismiss(id), duration)
+}
+
+function dismiss(id) {
+  toasts.value = toasts.value.filter(t => t.id !== id)
+}
+
+return { toasts, show, dismiss }
+```
+
+2. **ToastContainer.vue** — new component, mounted in `App.vue`:
+```html
+<Teleport to="body">
+  <div class="fixed bottom-4 right-4 flex flex-col-reverse gap-2 z-[9999] pointer-events-none">
+    <TransitionGroup name="toast">
+      <div v-for="toast in toastStore.toasts" :key="toast.id"
+           class="pointer-events-auto flex items-center gap-3 bg-white rounded-xl shadow-lg border border-gray-100 pl-0 pr-4 py-3 max-w-sm min-w-[280px]"
+           @click="toastStore.dismiss(toast.id)">
+        <!-- Left color bar -->
+        <div class="w-1 self-stretch rounded-l-xl" :class="accentClass(toast.type)"></div>
+        <!-- Icon -->
+        <AppIcon :name="iconForType(toast.type)" class="w-5 h-5 shrink-0" :class="iconColorClass(toast.type)" />
+        <!-- Message -->
+        <p class="text-sm text-gray-800 flex-1">{{ toast.message }}</p>
+      </div>
+    </TransitionGroup>
+  </div>
+</Teleport>
+```
+
+3. **Where to mount ToastContainer:** In `App.vue` template, alongside `<router-view>`. Since `App.vue` uses `<script setup>`, import and add `<ToastContainer />` to the template.
+
+4. **Phase 8 call sites that must remain unchanged:**
+   - `SettingsAccountTab.vue` — `useToastStore().show('Sessions revoked', 'success')`
+   - `TotpEnrollment.vue` — `useToastStore().show('TOTP enabled', 'success')`
+
+5. **New call sites to add (FileManagerView.vue):**
+   - Upload complete: `show('${files.length} file(s) uploaded', 'success')`
+   - Upload error: `show('Upload failed: ' + item.error, 'error')`
+   - Document deleted: `show('Document deleted', 'success')`
+   - Move to folder success: `show('Document moved', 'success')`
+   - Share revoked: `show('Share revoked', 'success')` — ShareModal emits this
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: App.vue is `<script setup>` but Project Convention is Options API
+
+**What goes wrong:** CLAUDE.md says "Options API preserved in v0.2 refactor" but `App.vue` is already `<script setup>`. Assuming Options API lifecycle hooks will fail silently.
+**Root cause:** App.vue was written in Composition API style when it was created (likely Phase 9). The Options API convention applies to new components, but App.vue is already Composition API.
+**Prevention:** Use `onMounted`/`onUnmounted` from Vue 3 in App.vue additions. New components (EmptyState, BreadcrumbBar, ToastContainer, OsDragOverlay) should be Options API per convention.
+
+### Pitfall 2: `dragend`-then-`click` on File Rows in StorageBrowser
+
+**What goes wrong:** File rows in StorageBrowser use `@click="$emit('file-open', file)"`. After a drag that covers < 4px, the browser fires `dragend` then immediately fires `click`, causing the document to open after the user intended a drag.
+**Root cause:** Pitfall 6 from PITFALLS.md — browser fires click after dragend below drag initiation threshold.
+**Prevention:** Add `draggingFile` state guard to file row click: `:@click="draggingFile ? null : $emit('file-open', file)"`. Reset `draggingFile` to `null` in `@dragend` with a `nextTick` delay so the click guard has time to intercept: `@dragend="nextTick(() => { draggingFile = null })"`.
+
+### Pitfall 3: OS Drag Overlay Bleeding into In-App Element Drags
+
+**What goes wrong:** The OS drag overlay checks `dataTransfer.types.includes('Files')` — but this must only fire when the drag originates from OUTSIDE the browser. An in-app element drag (file row to folder row) will NOT have `'Files'` in types, so this should be safe. However, the `dragenter` event fires on EVERY element the cursor passes over. If the overlay is shown based on `dragenter` alone, it will flicker.
+**Prevention:** Use a counter pattern: increment `dragDepth` on `dragenter`, decrement on `dragleave`. Show overlay when `dragDepth > 0 && isFilesDrag`. Reset to 0 on `drop`. This prevents premature hide when cursor moves between child elements.
+
+### Pitfall 4: Keyboard `Escape` Double-Firing with DocumentPreviewModal
+
+**What goes wrong:** `DocumentPreviewModal.vue` registers its OWN `document.addEventListener('keydown', handleKeydown)` that emits `close` on `Escape`. If App.vue ALSO registers a global handler that tries to close modals on `Escape`, both fire.
+**Root cause:** DocumentPreviewModal manages its own close. The App.vue Escape handler must NOT attempt to close modals directly — it should only clear the search bar when no modal is open, or be a no-op when a modal is open.
+**Prevention:** Track open modal state in a Pinia store (e.g., `useModalStore` with `openModal: ref(null)`). App.vue Escape handler checks: if `modalStore.openModal`, do nothing (let the modal's own listener handle it). Else: clear search query.
+**Alternative:** Don't register Escape in App.vue at all — let each modal handle its own Escape, and only handle `/` and other non-conflicting shortcuts at the App.vue level. Escape for "clear search" can be handled inside `SearchBar.vue` directly.
+
+### Pitfall 5: Folder Picker Teleport Requires Tracking Which Button Triggered It
+
+**What goes wrong:** Teleporting the folder picker out of the file row means the picker's position must be calculated from the trigger button's `getBoundingClientRect()`. If multiple files have their picker open (impossible due to `folderPickerFileId` being a single ref), or if the scroll position changes after opening, the picker floats at the wrong position.
+**Prevention:** Call `updatePickerPosition()` on `scroll` events (same pattern as SearchableModelSelect.vue which registers `window.addEventListener('scroll', onScroll, true)`). Store the computed position in a reactive `pickerStyle` ref.
+
+### Pitfall 6: Toast `z-index` vs Drag Overlay
+
+**What goes wrong:** ToastContainer uses `z-[9999]`. OsDragOverlay uses `fixed inset-0` — it must have a z-index that covers the entire page including dropdowns but does NOT cover the toast stack.
+**Prevention:** `OsDragOverlay` uses `z-[9998]`. `ToastContainer` uses `z-[9999]`. `DocumentPreviewModal` uses `z-50`. The drop overlay renders ABOVE the main content but BELOW toasts so upload feedback is visible even during an active drop.
+
+### Pitfall 7: Skeleton Row Height Must Match Real Row Height
+
+**From PITFALLS.md §Pitfall 13:** Skeleton rows that are different heights from actual rows cause layout shift (CLS) when real content loads.
+**StorageBrowser grid row height:** `px-4 py-2.5` with grid `grid-cols-[2rem_1fr_6rem_8rem_6rem]`. Skeleton rows must use identical classes with `animate-pulse` gray blocks:
+```html
+<div class="px-4 py-2.5 grid grid-cols-[2rem_1fr_6rem_8rem_6rem] gap-3 items-center">
+  <div class="w-7 h-7 bg-gray-100 rounded-lg animate-pulse"></div>
+  <div class="h-4 bg-gray-100 rounded animate-pulse w-2/3"></div>
+  <div class="h-3 bg-gray-100 rounded animate-pulse hidden md:block"></div>
+  <div class="h-3 bg-gray-100 rounded animate-pulse hidden sm:block"></div>
+  <div class="w-14 h-3 bg-gray-100 rounded animate-pulse"></div>
+</div>
+```
+
+---
+
+## Code Examples
+
+### AppIcon.vue — Settings icon (dual-path case)
+
+```html
+<!-- Source: direct audit of AppSidebar.vue, verified from source -->
+<template>
+  <svg :class="$attrs.class" fill="none" stroke="currentColor"
+       viewBox="0 0 24 24" aria-hidden="true">
+    <template v-if="Array.isArray(paths[name])">
+      <path v-for="(d, i) in paths[name]" :key="i"
+            stroke-linecap="round" stroke-linejoin="round" stroke-width="2" :d="d" />
+    </template>
+    <path v-else
+          stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+          :d="paths[name]" />
+  </svg>
+</template>
+<script>
+export default {
+  name: 'AppIcon',
+  inheritAttrs: false,
+  props: { name: { type: String, required: true } },
+  computed: {
+    paths() { return this.$options._iconPaths }
+  },
+  _iconPaths: {
+    folder: 'M3 7a2 2 0 012-2h4l2 2h8a2 2 0 012 2v9...',
+    cog: [
+      'M10.325 4.317c.426-1.756 2.924-1.756 3.35 0...',
+      'M15 12a3 3 0 11-6 0 3 3 0 016 0z'
+    ],
+    // ...
+  }
+}
+</script>
+```
+
+### Global keydown handler in App.vue (Composition API)
+
+```javascript
+// Source: direct audit of App.vue (uses <script setup>) + DocumentPreviewModal.vue pattern
+import { onMounted, onUnmounted, ref } from 'vue'
+import { useRoute } from 'vue-router'
+
+const routeViewRef = ref(null)  // <router-view ref="routeViewRef" />
+
+function onKeydown(e) {
+  const tag = document.activeElement?.tagName
+  if (['INPUT', 'TEXTAREA', 'SELECT'].includes(tag) || document.activeElement?.isContentEditable) return
+
+  if (e.key === '/' && !e.ctrlKey && !e.metaKey) {
+    e.preventDefault()
+    routeViewRef.value?.focusSearch?.()
+  }
+  if (e.key === 'Escape') {
+    routeViewRef.value?.clearSearch?.()
+  }
+  if (e.key === 'u' || e.key === 'U') {
+    routeViewRef.value?.triggerUpload?.()
+  }
+  if (e.key === 'n' || e.key === 'N') {
+    routeViewRef.value?.startNewFolder?.()
+  }
+}
+
+onMounted(() => document.addEventListener('keydown', onKeydown))
+onUnmounted(() => document.removeEventListener('keydown', onKeydown))
+```
+
+### OsDragOverlay — depth counter pattern
+
+```javascript
+// Source: derived from D-16 + Pitfall 3 analysis (ASSUMED pattern — standard solution)
+let dragDepth = 0
+
+function onDragEnter(e) {
+  if (!e.dataTransfer?.types.includes('Files')) return
+  dragDepth++
+  showOverlay.value = true
+}
+function onDragLeave() {
+  dragDepth = Math.max(0, dragDepth - 1)
+  if (dragDepth === 0) showOverlay.value = false
+}
+function onDrop(e) {
+  dragDepth = 0
+  showOverlay.value = false
+  const files = Array.from(e.dataTransfer.files)
+  if (files.length) emit('files-dropped', files)
+}
+onMounted(() => {
+  window.addEventListener('dragenter', onDragEnter)
+  window.addEventListener('dragleave', onDragLeave)
+  window.addEventListener('dragover', e => e.preventDefault())
+  window.addEventListener('drop', onDrop)
+})
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|---|---|---|---|
+| Spinner/text "Loading…" | Structured skeleton rows matching grid layout | Phase 10 | Eliminates layout shift; communicates content shape before data loads |
+| Inline empty "No items" text | `EmptyState.vue` with icon + headline + subtext + CTA slot | Phase 10 | Consistent visual language; actionable empty states |
+| Per-file SVG blocks | `AppIcon.vue` name→path registry | Phase 10 | Deduplication; single update point for icon changes |
+| Per-view breadcrumb (FolderBreadcrumb) | Shared `BreadcrumbBar.vue` with static segments support | Phase 10 | Consistent breadcrumb across all contexts |
+| Silent feedback on actions | Toast notifications via `useToastStore` | Phase 10 | Users know actions succeeded or failed |
+
+**Deprecated/outdated after Phase 10:**
+- `FolderBreadcrumb.vue`: deleted after BreadcrumbBar.vue is wired
+- `"Loading…"` text in StorageBrowser, AppSidebar, AdminUsersView, AdminAuditView: replaced by skeletons
+- `"No folders yet"` / `"No topics yet"` / `"No cloud storage connected"` plain text: replaced by EmptyState.vue
+- Inline `<svg>` blocks across 29 files: replaced by `<AppIcon name="..." />`
+- AppSidebar `startNewFolder()` / `cancelNewFolder()` / `submitNewFolder()` functions and their local state: these are the SIDEBAR folder creation functions being removed (UX-14). The file manager's own inline new-folder UI in StorageBrowser is KEPT.
+
+---
+
+## Wave / Dependency Plan
+
+### Wave 0 — Foundation Components (all parallel, no inter-dependencies)
+
+**Goal:** Create new shared components and update the toast store. No wiring to call sites yet.
+
+| Req(s) | Task | Files Created/Modified |
+|---|---|---|
+| CODE-05 | Create `AppIcon.vue` with complete `name→path` map (all ~30 icons) | `components/ui/AppIcon.vue` NEW |
+| UX-01 | Create `EmptyState.vue` with `icon`, `headline`, `subtext` props + `#cta` slot | `components/ui/EmptyState.vue` NEW |
+| UX-12 | Create `BreadcrumbBar.vue` extending FolderBreadcrumb interface | `components/ui/BreadcrumbBar.vue` NEW |
+| UX-10 | Implement `useToastStore` reactive state + `ToastContainer.vue` + mount in `App.vue` | `stores/toast.js` MODIFIED, `components/ui/ToastContainer.vue` NEW, `App.vue` MODIFIED |
+
+**Wave 0 rationale:** All four tasks produce standalone components / updated store. None depend on each other and none modify existing call sites — so a failure in one task does not block others.
+
+---
+
+### Wave 1 — Wire Empty States, Skeletons, Toast Call Sites (parallel within wave, blocked on Wave 0)
+
+**Goal:** Replace all "Loading…" / "No items" text across the app. Add toast calls to existing actions.
+
+| Req(s) | Task | Files Modified |
+|---|---|---|
+| UX-02 | Add 5-col skeleton rows to `StorageBrowser.vue` (replace "Loading…" div) | `StorageBrowser.vue` |
+| UX-03 | Add skeleton placeholders to `AppSidebar.vue` folder tree + topics + cloud sections | `AppSidebar.vue` |
+| UX-04 | Add skeleton table rows to `AdminUsersView.vue` + `AdminAuditView.vue` | `AdminUsersView.vue`, `AdminAuditView.vue` |
+| UX-01 | Wire `EmptyState.vue` into: StorageBrowser (root, folder, search), SharedView, CloudStorageView, AppSidebar, AdminAuditView | `StorageBrowser.vue`, `SharedView.vue`, `CloudStorageView.vue`, `AppSidebar.vue`, `AdminAuditView.vue` |
+| UX-10 | Add toast calls to `FileManagerView.vue` (upload, delete, move, rename, share revoke) | `FileManagerView.vue` |
+| UX-12 | Replace `FolderBreadcrumb` usages with `BreadcrumbBar`; add static segments to admin/settings views; delete `FolderBreadcrumb.vue` | `StorageBrowser.vue`, `FileManagerView.vue`, `CloudFolderView.vue`, and 5 admin/settings views |
+| UX-14 | Remove "New" button from `AppSidebar.vue` sidebar + all associated `startNewFolder` sidebar state | `AppSidebar.vue` |
+
+---
+
+### Wave 2 — Keyboard Shortcuts + OS Drag Overlay (parallel, blocked on Wave 0)
+
+**Goal:** Keyboard navigation and OS file drag upload.
+
+| Req(s) | Task | Files Modified |
+|---|---|---|
+| UX-05, UX-06, UX-07, UX-08 | Add global keydown handler to `App.vue`; expose `focusSearch`, `triggerUpload`, `startNewFolder`, `clearSearch` on `FileManagerView.vue`; expose `triggerInput` on `DropZone.vue`; expose `triggerUpload` on `StorageBrowser.vue`; add `focusSearch` chain through `SearchBar.vue` | `App.vue`, `FileManagerView.vue`, `StorageBrowser.vue`, `DropZone.vue`, `SearchBar.vue` |
+| UX-09 | Create `OsDragOverlay.vue` (depth counter, full-screen visual, Teleport to body); mount in `App.vue`; connect to `FileManagerView.vue` upload flow | `OsDragOverlay.vue` NEW, `App.vue` MODIFIED |
+
+---
+
+### Wave 3 — Drag-to-Move Completion + Dropdown Fixes + SVG Migration (parallel within wave, blocked on Waves 0-1)
+
+**Goal:** Wire drag-to-move toast, fix dropdown clipping, replace all inline SVGs.
+
+| Req(s) | Task | Files Modified |
+|---|---|---|
+| UX-11 | Add success/error toast to `FileManagerView.doMove()`; verify ring-2 highlight renders; add `DocumentCard.vue` drag guard (if DocumentCard gains draggable in this phase) | `FileManagerView.vue`, optionally `DocumentCard.vue` |
+| UX-13 | Teleport folder pickers in `StorageBrowser.vue` and `DocumentCard.vue` with `getBoundingClientRect()` positioning; Teleport `FolderRow.vue` dropdown menu | `StorageBrowser.vue`, `DocumentCard.vue`, `FolderRow.vue` |
+| CODE-05 | Replace all inline `<svg>` blocks across 29 files with `<AppIcon name="..." class="..." />` | All 29 files with inline SVGs |
+
+**Wave 3 rationale:** SVG migration (CODE-05) requires AppIcon.vue from Wave 0 but can proceed independently of Waves 1-2 after Wave 0. Dropdown fixes and drag completion are similarly independent of each other.
+
+---
+
+## Validation Architecture
+
+*(nyquist_validation: true in .planning/config.json)*
+
+### Test Framework
+
+| Property | Value |
+|---|---|
+| Framework | Vitest (already configured — PERF-01 installed `@vueuse/core` etc in Phase 8) |
+| Config file | `frontend/vite.config.js` (contains `test:` block if Phase 8 configured it) |
+| Quick run command | `cd frontend && npm run test -- --run` |
+| Full suite command | `cd frontend && npm run test` |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|---|---|---|---|---|
+| UX-01 | EmptyState renders icon + headline + subtext; CTA slot renders when provided | unit | `npm run test -- --run EmptyState` | ❌ Wave 0 |
+| UX-02 | StorageBrowser renders skeleton rows when `loading=true`; "Loading…" text absent | unit | `npm run test -- --run StorageBrowser` | ❌ Wave 0 |
+| UX-05 | `/` key focuses search input (not when input focused) | unit (simulate keydown) | `npm run test -- --run keyboard` | ❌ Wave 2 |
+| UX-06 | `Escape` clears search; fires only when no input is focused | unit | `npm run test -- --run keyboard` | ❌ Wave 2 |
+| UX-07 | `U` key calls `triggerInput()` on DropZone (not when input focused) | unit | `npm run test -- --run keyboard` | ❌ Wave 2 |
+| UX-08 | `N` key calls `startNewFolder()` (not when input focused) | unit | `npm run test -- --run keyboard` | ❌ Wave 2 |
+| UX-10 | Toast appears within 200ms of `show()` call; auto-dismisses after duration; disappears on click | unit | `npm run test -- --run toast` | ❌ Wave 0 |
+| UX-10 | Toast does not appear when `show()` is called with existing Phase 8 call-site signatures | unit | `npm run test -- --run toast` | ❌ Wave 0 |
+| UX-11 | `file-move` emit received → toast fires; ring class applied during dragOver | unit | `npm run test -- --run StorageBrowser` | ❌ Wave 3 |
+| UX-12 | BreadcrumbBar renders segments; last segment non-clickable; navigate emitted on segment click | unit | `npm run test -- --run BreadcrumbBar` | ❌ Wave 0 |
+| UX-13 | Dropdown picker renders at correct viewport position (getBoundingClientRect mock) | unit | `npm run test -- --run dropdown` | ❌ Wave 3 |
+| UX-14 | AppSidebar does not render "New" button in folder section | unit | `npm run test -- --run AppSidebar` | ❌ Wave 1 |
+| CODE-05 | AppIcon renders correct SVG path for each named icon; warns in dev for unknown name | unit | `npm run test -- --run AppIcon` | ❌ Wave 0 |
+| UX-09 | OS drag overlay appears on window dragenter with Files type; hidden on dragleave | unit | `npm run test -- --run OsDragOverlay` | ❌ Wave 2 |
+
+**Manual-only tests (cannot be automated in unit tests):**
+- UX-03: Sidebar skeleton visual appearance — verify skeletons match TreeItem indent levels visually
+- UX-04: Admin table skeleton rows — verify column alignment matches real rows
+- Toast stacking behavior with multiple simultaneous toasts
+- OS drag-and-drop actual file upload end-to-end flow
+- Keyboard shortcut: `N` in a cloud folder view (should be a no-op)
+
+### Key Behavioral Contracts
+
+| Contract | Value | Test Type |
+|---|---|---|
+| Toast auto-dismiss timing | 4000ms (locked by Phase 8 stub default) | unit (mock timers) |
+| Toast manual dismiss | click anywhere on toast | unit |
+| Keyboard guard: `/` inside focused input | does NOT redirect to search | unit |
+| Keyboard guard: `N` inside focused input | does NOT trigger folder creation | unit |
+| Breadcrumb last segment | non-clickable (no `@click` / `@navigate` on last segment) | unit |
+| OS drag detection | `dataTransfer.types.includes('Files')` required | unit |
+| Drag-to-move ring highlight | `ring-2 ring-inset ring-amber-300` class on hover target | unit |
+| AppIcon unknown name | logs `console.warn` in dev; renders nothing | unit |
+
+### Sampling Rate
+
+- **Per task commit:** `cd frontend && npm run test -- --run [component-name]`
+- **Per wave merge:** `cd frontend && npm run test -- --run`
+- **Phase gate:** Full suite green before `/gsd:verify-work`
+
+### Wave 0 Gaps
+
+- [ ] `frontend/src/components/ui/AppIcon.test.js` — covers CODE-05 (name→path rendering, unknown name warn)
+- [ ] `frontend/src/components/ui/EmptyState.test.js` — covers UX-01 (props, CTA slot)
+- [ ] `frontend/src/components/ui/BreadcrumbBar.test.js` — covers UX-12 (last segment, navigate emit)
+- [ ] `frontend/src/stores/toast.test.js` — covers UX-10 (show, auto-dismiss, dismiss on click)
+- [ ] `frontend/src/components/ui/ToastContainer.test.js` — covers UX-10 visual rendering
+
+---
+
+## Security Domain
+
+Phase 10 is purely frontend UX. No new API endpoints, no authentication changes, no sensitive data handling. Security checklist items:
+
+| ASVS Category | Applies | Standard Control |
+|---|---|---|
+| V2 Authentication | no | — |
+| V3 Session Management | no | — |
+| V4 Access Control | no | — |
+| V5 Input Validation | no | Toast messages are internal strings, not user input |
+| V6 Cryptography | no | — |
+
+**Note:** The OS drag overlay receives `dataTransfer.files` — these are files selected by the user from their own OS. The upload flow calls the same `docsStore.upload()` path already used by DropZone. No new attack surface. The existing quota enforcement, MIME type validation, and backend file handling are unchanged.
+
+**Security gate items for Phase 10:**
+- `npm audit --audit-level=high` — verify no high/critical CVEs introduced (no new packages, should be clean)
+- `bandit -r backend/` — unchanged (backend untouched this phase)
+- Verify no keyboard shortcut can trigger privileged actions (U, N only fire upload picker and folder input — no data deletion or admin actions)
+
+---
+
+## Open Questions
+
+1. **UploadProgress.vue solid icons**
+   - What we know: `UploadProgress.vue` uses solid (fill-based) `<svg>` for error-circle and checkmark-circle, which differ from the stroke-only convention.
+   - What's unclear: Should CODE-05 replace these with stroke equivalents or keep them as inline SVG?
+   - Recommendation: Replace with stroke equivalents (`checkCircle` = `M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z` and `exclamationCircle`) already in the AppIcon map. The visual difference (solid vs stroke) is minor at w-5 h-5 and the consistency benefit outweighs it.
+
+2. **`N` shortcut in cloud folder view**
+   - What we know: `N` should start new folder. But `CloudFolderView.vue` (cloud file manager) does not have folder creation — cloud folders are managed by the provider.
+   - What's unclear: Should `N` be a no-op in cloud context, or show a "not available in cloud" toast?
+   - Recommendation: No-op. The App.vue handler calls `routeViewRef.value?.startNewFolder?.()` with optional chaining — if CloudFolderView doesn't expose `startNewFolder`, nothing happens. No toast needed.
+
+3. **BreadcrumbBar in SettingsView**
+   - What we know: SettingsView uses tabs, not routes. The "active tab" changes without route change.
+   - What's unclear: Should BreadcrumbBar update when the active settings tab changes? UX-12 says "breadcrumb updates on navigation" — tab changes are not route navigations.
+   - Recommendation: Static breadcrumb for settings showing `Settings › Account` (or whichever tab). Update the segments computed when `activeTab` changes using a `computed()`. This is a pure UI update, not a route change.
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|---|---|---|
+| A1 | Total SVG `<path>` count is 66 across 29 files | Component Inventory §1 | Low — count was derived from grep output; off-by-one would not affect plan |
+| A2 | `FolderRow.vue` three-dot menu should use stroke equivalent of dots icon | Component Inventory §1 (Special Cases) | Low — keeping inline fill-based icon is valid fallback |
+| A3 | Heroicons outline search path: `M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0` | Component Inventory §3 | Medium — verify at heroicons.com before committing to AppIcon.vue |
+| A4 | `npm run test -- --run` is the correct Vitest command format for this project | Validation Architecture | Low — if wrong, use `npx vitest run` |
+| A5 | `SearchBar.vue` does not currently expose its input via `defineExpose` | Keyboard Shortcut section | Low — check SearchBar.vue source before plan is written if not already read |
+
+---
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|---|---|---|---|---|
+| Node.js + npm | Frontend build | ✓ | (project running) | — |
+| Vue 3 | All components | ✓ | ^3.5.x (Phase 8) | — |
+| Pinia | Toast store | ✓ | already installed | — |
+| Tailwind CSS | Skeleton animate-pulse, ring utilities | ✓ | already installed | — |
+| `<Teleport>` | ToastContainer, dropdown fixes | ✓ | Vue 3 built-in | — |
+
+No missing dependencies. Phase 10 requires no new installations.
+
+---
+
+## Sources
+
+### Primary (HIGH confidence — direct source inspection)
+- `frontend/src/components/storage/StorageBrowser.vue` — drag state, breadcrumb props, empty state, loading, defineExpose
+- `frontend/src/views/FileManagerView.vue` — browserRef pattern, upload handler, folder CRUD
+- `frontend/src/components/layout/AppSidebar.vue` — "New" button (UX-14), loading text, empty text, sidebar sections
+- `frontend/src/stores/toast.js` — Phase 8 stub, locked signature
+- `frontend/src/App.vue` — layout structure, `<script setup>` usage
+- `frontend/src/components/folders/FolderBreadcrumb.vue` — current breadcrumb interface (segments, navigate emit)
+- `frontend/src/components/ui/SearchableModelSelect.vue` — Teleport + getBoundingClientRect dropdown pattern (reference implementation)
+- `frontend/src/components/documents/DocumentPreviewModal.vue` — keydown listener pattern reference
+- All 29 Vue files with inline SVGs — path `d` attribute values extracted directly
+
+### Secondary (MEDIUM confidence)
+- `.planning/research/PITFALLS.md` — Pitfalls 6, 7, 12, 13 (documented from prior source audit in v0.2 research phase)
+- `.planning/research/ARCHITECTURE.md` — component responsibility map and integration points
+
+### Tertiary (LOW confidence / ASSUMED)
+- Heroicons search path value (A3) — training knowledge, not verified against heroicons.com this session
+- Exact Vitest command format (A4) — training knowledge; verify against `package.json` scripts
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Component inventory (SVG audit, dropdown audit, empty state contexts): HIGH — sourced directly from file reads
+- Drag-to-move current state: HIGH — sourced directly from StorageBrowser.vue source
+- BreadcrumbBar extraction: HIGH — sourced directly from FolderBreadcrumb.vue
+- Upload ref chain: HIGH — sourced directly from FileManagerView.vue + StorageBrowser.vue + DropZone.vue
+- Keyboard shortcut home (App.vue): HIGH — sourced directly from App.vue
+- Toast implementation: HIGH — stub contract is clear; implementation pattern is standard Pinia + Vue
+- Test framework detection: MEDIUM — vite.config.js not read; assumed from Phase 8 PERF-01 install
+- Heroicons icon paths (A3): LOW — training data, not verified
+
+**Research date:** 2026-06-14
+**Valid until:** 2026-07-14 (stable stack — no version-sensitive claims)