chore: archive v0.2 phase directories to milestones/v0.2-phases/

Moves phases 08–11 execution artifacts from .planning/phases/ to
.planning/milestones/v0.2-phases/ to keep .planning/phases/ clean
for the next milestone.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -5,4 +5,5 @@ backend/data/
 frontend/node_modules/
 frontend/dist/
 frontend/package-lock.json
+frontend/stats.html
 screenshots/

.planning/MILESTONES.md

@@ -0,0 +1,37 @@
+# DocuVault — Milestones
+
+## v0.2 — UI Overhaul and Optimization
+
+**Shipped:** 2026-06-17
+**Phases:** 8–11 (4 phases, 33 plans)
+**Timeline:** 2026-06-07 → 2026-06-17 (10 days)
+**Git range:** docs: define milestone v0.2 requirements → docs(milestone): mark v0.2 audit passed
+**Files changed:** 236 files, +39,557 / −6,288 lines, 198 commits
+
+### Delivered
+
+Transformed the frontend from rough alpha to polished, production-quality web app. Three backend router monoliths decomposed into focused sub-packages; `client.js` decomposed into 7 domain modules. Admin panel moved to standalone `/admin/*` route subtree with correct auth guard. Full UX interaction layer (empty states, skeletons, keyboard shortcuts, OS drag-drop, toasts, breadcrumbs, drag-to-move). Mobile-responsive layout with hamburger sidebar drawer. Bundle reduced −81 kB (−30.6%) via lazy loading.
+
+### Key Accomplishments
+
+1. Backend monolith decomposition — `api/admin.py` (934L), `api/documents.py` (852L), `api/auth.py` (825L) split into focused sub-packages; shared schemas extracted to `api/schemas.py`
+2. Frontend client decomposition — `client.js` (635L) → 7 domain modules + utils.js + barrel re-export; zero consumer churn across 35+ import sites
+3. Admin panel rearchitecture — standalone `/admin/*` subtree, `AdminLayout.vue`, `AdminSidebar.vue`, 5 deep-linkable views, overview aggregate endpoint, `to.matched.some()` auth guard
+4. UX interaction layer — `EmptyState.vue`, skeleton loaders, keyboard shortcuts (`/` `U` `N` `Escape`), `OsDragOverlay.vue`, Pinia toast store + `ToastContainer.vue`, `BreadcrumbBar.vue`, drag-to-move with Teleport dropdowns, `AppIcon.vue` (66 SVG instances centralized)
+5. Responsive design — hamburger sidebar drawer (below `lg`), adaptive document list columns, 36px touch targets, scrollable modals, `@tailwindcss/forms` baseline, Tailwind-only spacing/typography
+6. Bundle optimization — all admin routes lazy-loaded; dead code deleted (`FolderRow.vue`, `AccountView.vue`, stale test files); final bundle −81 kB vs baseline
+
+### Requirements
+
+40/40 satisfied (100%). No known gaps.
+
+### Archive
+
+- Roadmap: `.planning/milestones/v0.2-ROADMAP.md`
+- Requirements: `.planning/milestones/v0.2-REQUIREMENTS.md`
+- Audit: `.planning/milestones/v0.2-MILESTONE-AUDIT.md`
+- Phases: `.planning/phases/08-*/`, `09-*/`, `10-*/`, `11-*/`
+
+---
+
+*For project history prior to v0.2, see v0.1 milestone (not yet archived — v0.1 phases remain in `.planning/phases/01-*/` through `07.4-*/`).*

.planning/PROJECT.md

@@ -8,17 +8,11 @@ DocuVault is a self-hosted, multi-user SaaS document management platform. Users
 
 Every user's documents — and the credentials they use to store them — are inaccessible to everyone except that user, while the platform scales horizontally and supports pluggable storage backends.
 
-## Current Milestone: v0.2 — UI Overhaul and Optimization
+## Last Milestone: v0.2 — UI Overhaul and Optimization (shipped 2026-06-17)
 
-**Goal:** Redesign the frontend into a polished, performant, and responsive interface, and overhaul both the backend and frontend codebase to senior-dev quality — minimal, DRY, readable code with no unnecessary comments.
+**Delivered:** Polished, production-quality frontend with mobile-responsive layout, full UX interaction layer, decomposed backend/frontend codebase, and standalone admin panel.
 
-**Target features:**
-- Visual redesign — refined Tailwind component system, consistent palette, typography, spacing
-- UX & interaction improvements — drag-and-drop upload, keyboard shortcuts, empty states, loading skeletons
-- Frontend performance — lazy loading, virtual scrolling, bundle size reduction, API response caching
-- Responsive / mobile layout — adaptive layouts for phones/tablets, touch-friendly controls
-- Proper admin panel — standalone admin interface with its own routes, layout, and nav (not tabs bolted onto the user app)
-- Codebase quality overhaul — eliminate duplication, extract shared utilities, delete dead code, flatten unnecessary abstractions; comments only where code alone is insufficient
+See `.planning/MILESTONES.md` and `.planning/milestones/v0.2-ROADMAP.md` for full archive.
 
 ## Requirements
 
@@ -49,9 +43,29 @@ Every user's documents — and the credentials they use to store them — are in
 - ✓ Celery retry backoff (30 s / 90 s / 270 s) on classification failure
 - ✓ Backend stateless — all state in PostgreSQL and MinIO
 
-### Active (v0.2 — this milestone)
+### Validated (v0.2 — shipped 2026-06-17)
 
-*Defined in REQUIREMENTS.md*
+- ✓ Backend monolith decomposition (api/admin/, api/documents/, api/auth/ sub-packages) — v0.2
+- ✓ Frontend API client decomposition (7 domain modules + barrel re-export) — v0.2
+- ✓ Admin panel standalone route subtree (/admin/*) with AdminLayout, AdminSidebar, 5 deep-linkable views — v0.2
+- ✓ requiresAdmin guard via to.matched.some() — v0.2
+- ✓ Admin overview aggregate endpoint (user count, storage, doc status, recent audit) — v0.2
+- ✓ EmptyState.vue in all zero-content contexts — v0.2
+- ✓ Skeleton loaders for all async-populated tables/lists/sidebars — v0.2
+- ✓ Keyboard shortcuts: / (search), U (upload), N (new folder), Escape (close/clear) — v0.2
+- ✓ OS drag-drop overlay (full-screen, file-type discriminated) — v0.2
+- ✓ Toast notification system (auto-dismiss, stacking, non-blocking) — v0.2
+- ✓ BreadcrumbBar.vue shared across all views — v0.2
+- ✓ Drag-to-move document to folder with Teleport-based dropdowns — v0.2
+- ✓ AppIcon.vue centralizing all SVG path data (66 instances) — v0.2
+- ✓ Mobile-responsive layout: hamburger sidebar drawer (below lg), touch targets ≥36px — v0.2
+- ✓ @tailwindcss/forms cross-browser form baseline — v0.2
+- ✓ Consistent Tailwind-only spacing/typography/focus-visible/hover states — v0.2
+- ✓ Bundle −81 kB (−30.6%) via lazy-loaded admin routes — v0.2
+- ✓ Dead code deleted (FolderRow.vue, AccountView.vue, stale test files) — v0.2
+- ✓ WHY-only comment policy enforced (CODE-09) — v0.2
+
+### Active (next milestone — not yet defined)
 
 ### Out of Scope
 
@@ -65,10 +79,10 @@ Every user's documents — and the credentials they use to store them — are in
 
 ## Context
 
-- **Current state**: v0.2 in progress — Phase 10 complete (2026-06-16). UX & Interaction layer ships: empty states, loading skeletons, keyboard shortcuts (/, U, N, Escape), OS drag-drop upload, toast notifications, BreadcrumbBar, AppIcon registry, drag-to-move, Teleport dropdowns. All 6 UAT gaps closed (plan 10-13): sidebar shimmer, search-at-root visibility, admin sidebar isolation, keyboard dispatch via matched.find(), Escape modifier, OS drop capture phase. 219 tests pass. Phase 11 (Visual Design, Responsive Layout & Cleanup) up next.
+- **Current state**: v0.2 shipped 2026-06-17. All 4 v0.2 phases complete: stack upgrade + decomposition (Phase 8), admin panel rearchitecture (Phase 9), UX interaction layer (Phase 10), visual design + responsive layout (Phase 11). 277 tests pass. Bundle −81 kB from baseline. App is mobile-responsive, keyboard-navigable, and fully polished. Ready for next milestone definition.
 - **Tech stack**: FastAPI 0.136+ (Python 3.12), SQLAlchemy 2.0 async, Alembic, MinIO SDK; Vue 3 (Options API), Pinia, Vue Router 4, Vite, Tailwind CSS.
 - **Code quality**: v0.1 was built feature-first under time pressure. Both backend and frontend contain duplication, inconsistent patterns, and components that grew beyond their original scope. v0.2 addresses this systematically.
-- **Admin panel**: Now a standalone /admin/* route subtree with AdminLayout as the route component, AdminSidebar with 5 nav links, and 5 dedicated view components. Old AdminView.vue and tab components deleted. Admin users are redirected to /admin on login; non-admin users are blocked from /admin/* by a correct to.matched.some() guard.
+- **Admin panel**: Standalone /admin/* route subtree with AdminLayout as the route component, AdminSidebar with 5 nav links, and 5 dedicated view components. AdminView.vue and legacy tab components deleted. Admin users redirect to /admin on login; non-admin blocked by to.matched.some() guard.
 - **Privacy constraint**: Admin role is a platform operator, not a content viewer. Cloud credentials encrypted with per-user HKDF key; API keys encrypted with separate HKDF domain. Neither is ever in an API response.
 
 ## Constraints
@@ -101,7 +115,11 @@ Every user's documents — and the credentials they use to store them — are in
 | Vite 6 upgrade | Resolved two moderate CVEs (CVE-2026-39363/39364) present in Vite 5; build time unchanged | Shipped Phase 8 (PERF-01) |
 | Admin login redirect (D-08) | Role check fires before router.push — admin → /admin, regular user → /; D-09 guard as belt-and-suspenders | Shipped Phase 9 |
 | Tailwind safelist with regex patterns | Dynamic color classes (sky=OneDrive, amber=admin audit badges) are tree-shaken without explicit safelist | Regex patterns cover all provider and event-type color families in tailwind.config.js |
-| GET /api/admin/overview as dedicated endpoint | Aggregated stats (user count, storage, doc status, recent audit) served in one request to avoid N+1 on admin load | Shipped Phase 9 (09-01) |
+| GET /api/admin/overview as dedicated endpoint | Aggregated stats (user count, storage, doc status, recent audit) served in one request to avoid N+1 on admin load | ✓ Shipped Phase 9 (09-01) |
+| AppIcon.vue SVG registry | 66 duplicate inline SVG blocks eliminated; single source of truth for all icon paths | ✓ Shipped Phase 10 (CODE-05) |
+| Teleport + getBoundingClientRect for dropdowns | Viewport-edge clipping eliminated without complex position logic; prerequisite for virtual scrolling | ✓ Shipped Phase 10 (UX-13) |
+| Admin routes lazy-loaded | All 5 admin views excluded from initial bundle; −81 kB (−30.6%) improvement | ✓ Shipped Phase 11 (PERF-03) |
+| Vite 8 upgrade for npm audit | Closed high-severity esbuild CVE present in Vite 5/6; npm audit now clean | ✓ Shipped Phase 11 (11-07) |
 
 ## Evolution
 
@@ -123,4 +141,4 @@ Last updated: 2026-06-16
 4. Update Context with current state
 
 ---
-*Last updated: 2026-06-13 — after Phase 9*
+*Last updated: 2026-06-17 — after v0.2 milestone*

.planning/REQUIREMENTS.md

@@ -1,150 +0,0 @@
-# DocuVault v0.2 — Requirements
-
-**Milestone:** v0.2 — UI Overhaul and Optimization
-**Created:** 2026-06-07
-**Total requirements:** 40
-
----
-
-## Quality Mandate (applies to all phases)
-
-Every line of code written or modified in v0.2 must be:
-
-- **Minimal:** smallest amount of code that correctly solves the problem. No speculative abstractions.
-- **DRY:** if the same logic exists twice, extract it. Duplication is a defect.
-- **Readable:** names things accurately. A reader should understand intent without comments.
-- **No redundant comments:** comments exist only where the *why* is non-obvious. Never explain what the code does.
-- **No dead code:** unreferenced files, components, or functions are deleted — not commented out.
-
----
-
-## CODE — Codebase Quality
-
-- [ ] **CODE-01**: Backend `api/admin.py` (934L) decomposed into `api/admin/` package with `users.py`, `quotas.py`, `ai.py`; `__init__.py` aggregates sub-routers under the existing `/api/admin` prefix. No URL changes, no behavior changes, all tests stay green.
-- [ ] **CODE-02**: `api/documents.py` (852L) decomposed into focused sub-modules (upload flow, content proxy, document CRUD, search/listing) within `api/documents/` package. Prefix and behavior unchanged.
-- [ ] **CODE-03**: `api/auth.py` (825L) decomposed into focused sub-modules (login/tokens, TOTP, password management, session management) within `api/auth/` package. Prefix and behavior unchanged.
-- [x] **CODE-04**: Frontend `api/client.js` (635L) decomposed into domain modules (`documents.js`, `auth.js`, `admin.js`, `folders.js`, `shares.js`, `cloud.js`, `topics.js`); `client.js` becomes the HTTP transport layer and re-export barrel. Zero changes to any of the 35+ consumer files.
-- [ ] **CODE-05**: All inline SVG blocks (~66 instances) replaced with `<AppIcon name="..." class="..." />`; all icon path data centralized in `components/ui/AppIcon.vue`. No duplicated path strings.
-- [x] **CODE-06**: Tailwind `safelist` configured for all dynamic class name patterns in `formatters.js` (provider colors, backgrounds, badge text). Production builds render topic and provider colors correctly.
-- [ ] **CODE-07**: All unreferenced files, components, stores, and unused imports deleted. No dead code retained.
-- [x] **CODE-08**: No duplicated Pydantic model definitions or shared validators across router files. Shared schemas extracted to dedicated modules.
-- [x] **CODE-09**: No comment in any file describes what the code does. Comments exist only where intent or constraint would not be obvious to a competent reader.
-
----
-
-## ADMIN — Admin Panel
-
-- [x] **ADMIN-08**: Admin panel moved to `/admin/*` route subtree with `AdminLayout.vue` as the route component. `AdminLayout` has its own sidebar with admin-specific nav only — no user quota bar, no folder tree, no topic list. `AdminView.vue` is deleted.
-- [x] **ADMIN-09**: Admin sidebar nav links (in order): Overview, Users, Quotas, AI Config, Audit Log. "Back to app" link at the bottom returns to `/`.
-- [x] **ADMIN-10**: Each admin section is its own deep-linkable URL (`/admin/users`, `/admin/quotas`, `/admin/ai`, `/admin/audit`). Browser back button works within the admin section.
-- [x] **ADMIN-11**: Admin overview page (`/admin`) shows: total registered user count, total platform storage in use, document status breakdown (processing/ready/failed), last 10 audit log entries. Requires new backend aggregate query endpoints.
-- [x] **ADMIN-12**: `requiresAdmin` guard enforced for all `/admin/*` child routes via `to.matched.some(r => r.meta.requiresAdmin)`. No admin child route is accessible to non-admin users.
-
----
-
-## UX — UX and Interaction
-
-- [ ] **UX-01**: Every zero-content context shows a contextually distinct empty state using a shared `EmptyState.vue` component (headline, subtext, optional CTA). Applied to: root file list, individual folder, search with no results, shared-with-me, topics list, audit log, cloud connections. No plain "No items" text remains.
-- [ ] **UX-02**: Document list (`StorageBrowser`) displays 5-col skeleton grid rows during loading (matching actual grid layout, `animate-pulse`). "Loading..." text removed.
-- [ ] **UX-03**: Sidebar folder tree and topics list display skeleton placeholder items during loading. "Loading..." text removed.
-- [ ] **UX-04**: Admin user table and audit log table display skeleton table rows during loading.
-- [ ] **UX-05**: Pressing `/` when no input is focused moves keyboard focus to the search bar.
-- [ ] **UX-06**: Pressing `Escape` closes any open modal (`ShareModal`, `FolderDeleteModal`, `DocumentPreviewModal`) and clears active search. Handled at the overlay level, not only inside inputs.
-- [ ] **UX-07**: Pressing `U` when no input is focused triggers the file upload picker.
-- [ ] **UX-08**: Pressing `N` when no input is focused starts the new folder inline input in the file manager.
-- [ ] **UX-09**: Dragging files from the OS anywhere onto the browser window shows a full-screen drop overlay. Releasing uploads the files via the existing upload flow. Only activates when `dataTransfer.types` includes `'Files'`.
-- [ ] **UX-10**: Toast notification system shows transient messages (auto-dismiss 4 seconds, manual dismiss on click) for: upload complete, upload error, document deleted, share revoked, rename successful. Toasts stack vertically and do not block interaction.
-- [ ] **UX-11**: Drag-to-move a document onto a folder row in `StorageBrowser` works correctly end-to-end. Drop highlight (`ring-2 ring-inset ring-amber-300`) renders on valid folder targets. "Move to folder" button remains as non-drag alternative.
-- [ ] **UX-12**: All views display a breadcrumb reflecting the full current navigation path. Examples: `Folders › Reports › Q1`, `Cloud › Google Drive › Projects`, `Admin › Users`, `Settings › Account`, `Folders › Reports › document.pdf`. Breadcrumb updates on navigation. A single shared breadcrumb component is used across all view types — no per-view implementations.
-- [ ] **UX-13**: All dropdown menus and modal dialogs render their full content within the viewport. No text or interactive element is clipped by a viewport edge or sibling element. Dropdowns that risk edge-clipping use fixed positioning computed from `getBoundingClientRect()` or `<Teleport to="body">`.
-- [ ] **UX-14**: The inline "New" button next to the Folders section header in `AppSidebar.vue` is removed. Folder creation accessible only from within the file manager view.
-
----
-
-## VISUAL — Visual Design
-
-- [ ] **VISUAL-01**: Consistent spacing scale across all components using Tailwind utilities only. No arbitrary `px-[13px]` values or inline `style` margins.
-- [ ] **VISUAL-02**: All form elements (inputs, selects, textareas, checkboxes, radio buttons) have consistent cross-browser baseline styling via `@tailwindcss/forms` plugin.
-- [ ] **VISUAL-03**: All interactive elements (buttons, links, card rows) have consistent hover states, `focus-visible:` rings, and active states.
-- [ ] **VISUAL-04**: Typography scale is consistent: one heading size per level, one body size, one label/caption size. No per-component font-size overrides.
-
----
-
-## RESP — Responsive Layout
-
-- [ ] **RESP-01**: Sidebar hidden below `lg` (1024px). Hamburger button in mobile-only header toggles a slide-in overlay drawer. Overlay closes on nav tap or backdrop tap.
-- [ ] **RESP-02**: Document list hides Size column below `md` (768px) and Modified column below `sm` (640px). Icon, name, and actions always visible.
-- [ ] **RESP-03**: Inline icon action buttons have minimum 36×36px touch target on viewports below `md`.
-- [ ] **RESP-04**: All modal dialogs are scrollable on viewports below 640px. No modal content overflows the screen.
-- [ ] **RESP-05**: Admin layout has the same responsive behavior as the user layout: admin sidebar hidden on mobile, hamburger shows admin nav drawer.
-
----
-
-## PERF — Performance and Stack
-
-- [ ] **PERF-01**: Frontend dependencies bumped/added: `vue@^3.5.0`, `vite@^6.4.3`, `@vueuse/core@^14.3.0`, `@vueuse/integrations@^14.3.0`, `sortablejs@^1.15.7`, `@tailwindcss/forms@^0.5.11`. Dev: `rollup-plugin-visualizer@^7.0.1`, `@types/sortablejs`.
-- [ ] **PERF-02**: Bundle baseline measured with `rollup-plugin-visualizer` before optimizations begin. Second measurement taken after all refactoring is complete. Both reports committed to `.planning/`.
-- [ ] **PERF-03**: All non-initial-render route components are lazy-loaded. Admin views explicitly lazy-loaded. No synchronous import for routes not on the critical render path.
-
----
-
-## Future (deferred)
-
-- Virtual scrolling — quota cap (100 MB/user) limits lists to hundreds of items; `v-for` is sufficient. Revisit with server-side pagination.
-- Dark mode — coherent color token system must exist first.
-- Folder reordering by drag — requires persistent `position` column in DB.
-- Multi-select with batch operations — low frequency in a personal vault.
-
-## Out of Scope
-
-- Composition API migration — refactor within Options API; Composition API is a separate milestone.
-- Component library switch (shadcn-vue, PrimeVue) — stay with Tailwind.
-- SSO, billing, group roles — v0.x exclusions unchanged from v0.1.
-- Document annotation or in-app editing — not planned.
-
----
-
-## Traceability
-
-| REQ-ID | Phase | Plan |
-|--------|-------|------|
-| PERF-01 | Phase 8 | Pending |
-| CODE-01 | Phase 8 | Pending |
-| CODE-02 | Phase 8 | Pending |
-| CODE-03 | Phase 8 | Pending |
-| CODE-04 | Phase 8 | Complete |
-| CODE-08 | Phase 8 | Complete |
-| ADMIN-08 | Phase 9 | Complete |
-| ADMIN-09 | Phase 9 | Complete |
-| ADMIN-10 | Phase 9 | Complete |
-| ADMIN-11 | Phase 9 | Complete |
-| ADMIN-12 | Phase 9 | Complete |
-| CODE-06 | Phase 9 | Complete |
-| CODE-09 | Phase 9 | Complete |
-| UX-01 | Phase 10 | Pending |
-| UX-02 | Phase 10 | Pending |
-| UX-03 | Phase 10 | Pending |
-| UX-04 | Phase 10 | Pending |
-| UX-05 | Phase 10 | Pending |
-| UX-06 | Phase 10 | Pending |
-| UX-07 | Phase 10 | Pending |
-| UX-08 | Phase 10 | Pending |
-| UX-09 | Phase 10 | Pending |
-| UX-10 | Phase 10 | Pending |
-| UX-11 | Phase 10 | Pending |
-| UX-12 | Phase 10 | Pending |
-| UX-13 | Phase 10 | Pending |
-| UX-14 | Phase 10 | Pending |
-| CODE-05 | Phase 10 | Pending |
-| VISUAL-01 | Phase 11 | Planned: 11-05 |
-| VISUAL-02 | Phase 11 | Planned: 11-04 |
-| VISUAL-03 | Phase 11 | Planned: 11-05 |
-| VISUAL-04 | Phase 11 | Planned: 11-05 |
-| RESP-01 | Phase 11 | Planned: 11-03 |
-| RESP-02 | Phase 11 | Planned: 11-03 |
-| RESP-03 | Phase 11 | Planned: 11-03 |
-| RESP-04 | Phase 11 | Planned: 11-04 |
-| RESP-05 | Phase 11 | Planned: 11-03 |
-| CODE-07 | Phase 11 | Planned: 11-06 |
-| PERF-02 | Phase 11 | Planned: 11-01, 11-06 |
-| PERF-03 | Phase 11 | Planned: 11-02 |

.planning/RETROSPECTIVE.md

@@ -0,0 +1,80 @@
+# DocuVault — Project Retrospective
+
+*A living document updated after each milestone. Lessons feed forward into future planning.*
+
+---
+
+## Milestone: v0.2 — UI Overhaul and Optimization
+
+**Shipped:** 2026-06-17
+**Phases:** 4 (8–11) | **Plans:** 33 | **Duration:** 10 days (2026-06-07 → 2026-06-17)
+**Git:** 198 commits, 236 files changed, +39,557 / −6,288 lines
+
+### What Was Built
+
+- Backend monolith decomposition — three router monoliths (934L, 852L, 825L) split into focused sub-packages with zero URL or behavior changes; shared schemas extracted to `api/schemas.py`
+- Frontend client decomposition — `client.js` (635L) → 7 domain modules + barrel re-export; 35+ consumer files unchanged
+- Admin panel rearchitecture — standalone `/admin/*` route subtree; `AdminLayout.vue`; `AdminSidebar.vue` with 5 nav links; 5 deep-linkable views; `to.matched.some()` auth guard fix; `GET /api/admin/overview` aggregate endpoint
+- UX interaction layer — `EmptyState.vue`, skeleton loaders, keyboard shortcuts (`/`, `U`, `N`, `Escape`), `OsDragOverlay.vue`, Pinia toast store + `ToastContainer.vue`, `BreadcrumbBar.vue`, drag-to-move with Teleport dropdowns, `AppIcon.vue` (66 SVG instances centralized)
+- Responsive design + visual polish — hamburger sidebar drawer (below `lg`), adaptive document list columns, 36px touch targets, scrollable modals, `@tailwindcss/forms` baseline, consistent Tailwind-only spacing/typography/focus-visible/hover states
+- Bundle optimization — all admin routes lazy-loaded; dead code deleted; bundle −81 kB (−30.6%) from baseline
+
+### What Worked
+
+- **Wave parallelization** — executing independent plans in parallel (e.g., CODE-01/02/03/04 in Phase 8 Wave 2) dramatically reduced wall-clock time; the wave structure in PLAN.md made this trivial to execute
+- **Barrel re-export pattern** — decomposing `client.js` with a barrel kept all 35+ consumer files unchanged; zero regressions, zero migration cost
+- **Foundation-then-wire order** — building `EmptyState.vue`, `BreadcrumbBar.vue`, `AppIcon.vue`, and the toast store as isolated components in Phase 10 Wave 0 before wiring them in Wave 1 kept each step reviewable and testable
+- **Teleport for dropdowns** — solving viewport-edge clipping with `Teleport to="body"` + `getBoundingClientRect()` was the right call; future virtual scrolling is now unblocked
+- **UAT gap closure plans** — having dedicated plans (10-13, 11-07) for UAT gaps rather than patching in-flight kept the execution clean and the gap closure auditable
+
+### What Was Inefficient
+
+- **Phase 8 progress table not updated** — the ROADMAP progress table showed "4/8 In Progress" for Phase 8 even after completion, discovered at milestone close. Progress table updates should be part of the plan execution checklist.
+- **Admin auth guard bug caught late** — the `to.meta.requiresAdmin` → `to.matched.some()` fix is a security-relevant change that wasn't caught until Phase 9. Nested route guards should be explicitly tested in Phase scaffolding.
+- **11-07 mobile toolbar gap** — the mobile compact toolbar fix was a UAT gap rather than planned; the RESP-02 success criterion should have been clearer about the 550px threshold from the start.
+- **Multiple SUMMARY.md formats** — some phase summaries used `**One-liner:**` and some used `## One-liner`; extracting them required heuristic grep patterns. A consistent frontmatter schema would help.
+
+### Patterns Established
+
+- **Sub-router NO-prefix rule** — `APIRouter()` in sub-packages must carry no `prefix`; the parent `include_router(sub, prefix=...)` propagates. This is now in CLAUDE.md.
+- **FastAPI 0.128+ empty-path restriction** — `@router.get("")` on a sub-router with empty include prefix raises `FastAPIError`; root routes must be registered on the parent aggregator directly.
+- **`to.matched.some()` for Vue Router 4 meta inheritance** — Vue Router 4 does not propagate `meta` to children automatically; direct `to.meta` checks are a security regression.
+- **AdminLayout as route component, not App.vue branch** — router resolves `AdminLayout` as the `/admin` component; its `<router-view>` renders children. `App.vue` needs no layout branching logic.
+- **Lazy-load all non-critical routes** — admin views and other non-initial-path routes should always be lazy-loaded by default; synchronous imports for non-critical routes are a bundle regression.
+
+### Key Lessons
+
+1. **Verify test coverage includes nested route behavior.** The `to.matched.some()` fix was a security-relevant change that required a specific negative test (non-admin navigating directly to `/admin/users`). Add nested-route auth tests to the scaffolding checklist for any phase that touches routing.
+2. **Write success criteria with explicit thresholds.** "Mobile responsive" in RESP-02 should have said "toolbar fits without horizontal scrolling at 375px and 550px" rather than leaving it implicit. Explicit viewport thresholds eliminate UAT guesswork.
+3. **Archive progress table state in the phase summary.** The ROADMAP progress table is read by the milestone close process; phases should update it as part of the "plan complete" ritual, not leave it for the orchestrator to discover at close.
+4. **Barrel re-export is the zero-friction decomposition pattern.** When splitting a large module, start with the barrel and establish the public API first. Consumer files never change; the decomposition is invisible to callers.
+
+### Cost Observations
+
+- Model: Claude Sonnet 4.6 throughout
+- No haiku or opus usage in v0.2
+- Notable: wave parallelization (3–5 independent plans per wave) was the primary efficiency lever; sequential execution of the same work would have taken ~2–3x longer
+
+---
+
+## Cross-Milestone Trends
+
+### Process Evolution
+
+| Milestone | Duration | Phases | Key Process Change |
+|-----------|----------|--------|--------------------|
+| v0.1 | ~16 days (2026-05-21→2026-06-06) | 11 (1–7.4) | Feature-first; security gates added mid-stream |
+| v0.2 | 10 days (2026-06-07→2026-06-17) | 4 (8–11) | Quality-first; wave parallelization; milestone audit before close |
+
+### Cumulative Quality
+
+| Milestone | Tests at close | Notes |
+|-----------|---------------|-------|
+| v0.1 | 347 | 1 pre-existing failure (missing module) |
+| v0.2 | 277 | Reduction reflects dead test file deletion; coverage per line improved |
+
+### Top Lessons (Verified Across Milestones)
+
+1. **Security gates must run before phase advance, not as a post-close checklist.** Both milestones had late-discovered security issues (v0.1: IDOR stubs, v0.2: auth guard). Bake the security agent into the plan execution ritual.
+2. **Explicit success criteria with measurable thresholds eliminate UAT gaps.** Vague criteria ("responsive") always produce UAT gap closure plans. Precise criteria ("at 375px and 550px viewport") do not.
+3. **Milestone audits before archival are worth the overhead.** The v0.2 audit caught stale artifacts and the esbuild CVE before the milestone was tagged. Running the audit as a prerequisite rather than a post-mortem saves remediation cost.

.planning/ROADMAP.md

@@ -522,219 +522,40 @@ Before any phase is marked complete, all three gates must pass:
 
 ---
 
-# DocuVault — v0.2 Roadmap
+## Milestones
 
-_Milestone: v0.2 — UI Overhaul and Optimization_
-_Started: 2026-06-07_
+- ✅ **v0.2 — UI Overhaul and Optimization** — Phases 8–11 (shipped 2026-06-17)
 
-## v0.2 Phases
+<details>
+<summary>✅ v0.2 — UI Overhaul and Optimization (Phases 8–11) — SHIPPED 2026-06-17</summary>
 
-- [x] **Phase 8: Stack Upgrade & Backend Decomposition** — Dependency bumps land; all three backend router monoliths split into focused sub-packages; frontend API client decomposed into domain modules; shared Pydantic schemas extracted _(2026-06-12)_
-- [x] **Phase 9: Admin Panel Rearchitecture** — Admin panel moves to `/admin/*` route subtree with its own layout, sidebar, and deep-linkable child routes; Tailwind safelist configured; redundant comments purged (completed 2026-06-12)
-- [x] **Phase 10: UX & Interaction** — Empty states, loading skeletons, keyboard shortcuts, drag-and-drop upload, toast notifications, breadcrumbs, and icon centralization land across the full UI (completed 2026-06-16)
-- [ ] **Phase 11: Visual Design, Responsive Layout & Cleanup** — Consistent spacing, form styling, hover/focus states, and typography applied; mobile-responsive sidebar and layouts ship; dead code deleted; bundle measured
+- [x] Phase 8: Stack Upgrade & Backend Decomposition (8/8 plans) — completed 2026-06-12
+- [x] Phase 9: Admin Panel Rearchitecture (5/5 plans) — completed 2026-06-13
+- [x] Phase 10: UX & Interaction (13/13 plans) — completed 2026-06-16
+- [x] Phase 11: Visual Design, Responsive Layout & Cleanup (7/7 plans) — completed 2026-06-17
 
-## Phase Details
+Full archive: `.planning/milestones/v0.2-ROADMAP.md`
 
-### Phase 8: Stack Upgrade & Backend Decomposition
+</details>
 
-**Goal**: The dependency stack is current, all three backend router monoliths are split into focused sub-packages with zero URL or behavior changes, and the frontend API client is decomposed into domain modules behind a re-export barrel — the entire change is invisible to consumers and tests.
-**Depends on**: Phase 7.4 (last v0.1 phase)
-**Requirements**: PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08
+## v0.2 + v0.1 Progress Table
 
-**Implementation notes:**
-- Sub-routers in `api/admin/`, `api/documents/`, `api/auth/` must have NO prefix on their `APIRouter()` — the parent prefix propagates. Adding a prefix doubles the URL path. (PITFALLS.md §Pitfall 1)
-- Shared Pydantic models, constants, and helpers that span sub-modules go in a `shared.py` within each package — never duplicated across sub-routers. (PITFALLS.md §Pitfall 2 — prevents circular imports)
-- `client.js` decomposition uses the re-export barrel pattern: `client.js` re-exports everything from domain sub-files; zero changes to the 35+ consumer files. `request()` and `noRefreshPaths` stay in `client.js`; the three blob-download 401-retry duplicates are consolidated into a single `fetchWithRetry()` helper. (PITFALLS.md §Pitfall 5)
-- CODE-01, CODE-02, CODE-03 are independent (touch different files) and can be executed in parallel. CODE-04 is also independent of the backend work.
-
-**Success Criteria** (what must be TRUE):
-1. `pytest -v` passes with zero failures immediately after the backend split — every existing API endpoint continues to respond on the same URL path
-2. `import * as api from '../api/client.js'` in any existing consumer file resolves all previously-exported names without modification to that consumer file
-3. No Pydantic model definition appears more than once across `api/admin/`, `api/documents/`, and `api/auth/` sub-packages — shared types live in a dedicated module
-4. `PERF-01` packages are installed and `npm list` confirms `vue@^3.5.x`, `vite@^6.x`, `@vueuse/core@^14.x`, `sortablejs`, `@tailwindcss/forms`, `rollup-plugin-visualizer` are present
-**Plans**: 8 plans (3 waves)
-
-**Wave 0** — Foundation (parallel)
-
-- [x] 08-01-PLAN.md — CR-01/02/03 test stubs (3 xfail stubs in test_auth.py) + Wave 0 scaffolds for regression detection
-- [x] 08-02-PLAN.md — `api/schemas.py` creation + `CloudConnectionOut` migration from admin.py (MUST precede admin split)
-
-**Wave 1** *(blocked on Wave 0)* — Phase 7.1 completion (frontend only — backend already implemented)
-
-- [x] 08-03-PLAN.md — `useToastStore` stub (`frontend/src/stores/toast.js`) + CR test promotion + SettingsAccountTab.vue + TotpEnrollment.vue inline toast replacement
-
-**Wave 2** *(blocked on Wave 1)* — Backend decomposition + frontend (parallel)
-
-- [x] 08-04-PLAN.md — Split `api/admin.py` → `api/admin/` package: users.py, quotas.py, ai.py, shared.py, __init__.py (CODE-01)
-- [x] 08-05-PLAN.md — Split `api/documents.py` → `api/documents/` package: upload.py, crud.py, content.py, shared.py, __init__.py (CODE-02)
-- [x] 08-06-PLAN.md — Split `api/auth.py` → `api/auth/` package: tokens.py, totp.py, password.py, sessions.py, shared.py, __init__.py (CODE-03)
-- [x] 08-07-PLAN.md — Frontend `client.js` decomposition: utils.js + 7 domain modules + barrel rewrite (CODE-04)
-- [x] 08-08-PLAN.md — PERF-01 dependency bump + tailwind/vite config wiring + requirements.txt exact pinning (PERF-01, D-17)
-
-**Cross-cutting constraints:**
-
-- Sub-routers MUST have NO prefix on `APIRouter()` — only package `__init__.py` carries the prefix (Plans 04, 05, 06)
-- `api/schemas.py` must exist before admin split — `api/cloud.py` imports `CloudConnectionOut` from admin (Plan 02 before Plan 04)
-- `request()` moves to `utils.js` for circular-import avoidance; `client.js` re-exports it — zero consumer changes (Plan 07)
-- Every admin sub-module handler retains `Depends(get_current_admin)` explicitly — never omit (Plans 04)
-
----
-
-### Phase 9: Admin Panel Rearchitecture
-
-**Goal**: The admin interface is a standalone route subtree (`/admin/*`) with its own layout component and sidebar; each admin section is deep-linkable and browser-back-button works; the `requiresAdmin` navigation guard correctly protects all child routes; and the Tailwind safelist is configured so dynamic color classes render correctly in production builds.
-**Depends on**: Phase 8
-**Requirements**: ADMIN-08, ADMIN-09, ADMIN-10, ADMIN-11, ADMIN-12, CODE-06, CODE-09
-
-**Implementation notes:**
-- `AdminLayout.vue` is registered as the `/admin` route's component; its `<router-view />` renders child views. `App.vue` does NOT need a third `v-else-if` branch — it renders whatever component the router resolves to. (PITFALLS.md §Pitfall 4)
-- The `beforeEach` guard must change from `to.meta.requiresAdmin` to `to.matched.some(r => r.meta.requiresAdmin)`. Vue Router 4 does not inherit `meta` from parent to children automatically. (PITFALLS.md §Pitfall 3)
-- `App.vue` layout resolution reads `route.matched.find(r => r.meta.layout)?.meta.layout` — same `matched` walk as the guard. (ARCHITECTURE.md §Integration Point 2)
-- `AdminLayout.vue` owns the `p-8 max-w-5xl mx-auto` content wrapper. Extracted tab-component-turned-views (`AdminUsersView.vue` etc.) must strip any top-level padding they inherited from `AdminView.vue` — double padding is the risk. (PITFALLS.md §Pitfall 9)
-- Tailwind safelist covers `providerColor`, `providerBg`, `providerLabel` dynamic pattern families from `formatters.js`. (PITFALLS.md §Pitfall 14)
-- CODE-09 (comment purge) applies to every file touched in this phase and retroactively to the backend sub-packages created in Phase 8.
-
-**Success Criteria** (what must be TRUE):
-1. Navigating directly to `/admin/users`, `/admin/quotas`, `/admin/ai`, and `/admin/audit` in a fresh browser tab loads the correct admin view with the admin sidebar — not the user app sidebar
-2. A logged-in non-admin user who navigates to `/admin/users` is redirected to `/` by the `beforeEach` guard; the redirect happens even when the URL is entered directly
-3. The browser back button moves from `/admin/audit` to `/admin/users` (or whichever path was previous) without a full page reload
-4. `AdminView.vue` is deleted from the repository; no file imports it
-5. A production build (`npm run build`) renders topic badge and provider chip colors correctly — no gray/invisible badges caused by purged dynamic Tailwind classes
-
-**Plans**: 5 plans (4 waves)
-
-**Wave 1** — Foundation (parallel)
-
-- [x] 09-01-PLAN.md — Backend overview.py endpoint + 8 ADMIN-11 tests (overview aggregate query + security invariants)
-- [x] 09-02-PLAN.md — Frontend AdminLayout + AdminSidebar + AdminOverviewView + getAdminOverview API client
-
-**Wave 2** *(blocked on 09-02)*
-
-- [x] 09-03-PLAN.md — Extract 4 admin tab components to standalone views (AdminUsersView, AdminQuotasView, AdminAiView, AdminAuditView)
-
-**Wave 3** *(blocked on 09-01, 09-02, 09-03)*
-
-- [x] 09-04-PLAN.md — Router rearchitecture (nested /admin + to.matched.some guard + D-08/D-09/D-10 redirects) + Tailwind safelist + LoginView admin redirect + delete AdminView.vue + 4 tab files
-
-**Wave 4** *(blocked on 09-04)*
-
-- [x] 09-05-PLAN.md — CODE-09 comment purge (Phase 9 files + retroactive Phase 8 backend sub-packages) + human checkpoint UAT
-
-**UI hint**: yes
-
----
-
-### Phase 10: UX & Interaction
-
-**Goal**: The application communicates state clearly at every moment — empty contexts have purposeful empty states, loading transitions show structured skeletons, power users can operate keyboard-first, files can be dragged from the OS directly onto the browser, and every action produces an immediate toast confirmation.
-**Depends on**: Phase 9
-**Requirements**: UX-01, UX-02, UX-03, UX-04, UX-05, UX-06, UX-07, UX-08, UX-09, UX-10, UX-11, UX-12, UX-13, UX-14, CODE-05
-
-**Implementation notes:**
-- Global `keydown` listener must guard against active input elements before firing any shortcut. The check pattern is: `['INPUT','TEXTAREA','SELECT'].includes(document.activeElement?.tagName) || document.activeElement?.isContentEditable` → early return. Register in `mounted()`, remove in `beforeUnmount()`. (PITFALLS.md §Pitfall 12)
-- Drag-and-drop upload (`UX-09`) detects `dataTransfer.types.includes('Files')` to distinguish file drags from element drags. The full-screen overlay must be attached at the `window`/`document` level, not inside `StorageBrowser`. (UX-09 requirement)
-- Drag-to-move (`UX-11`) is already partially implemented in `StorageBrowser.vue`. This phase wires it end-to-end and adds the `ring-2 ring-inset ring-amber-300` drop highlight on valid folder targets.
-- `DocumentCard.vue` drag must track `dragging` state to prevent the browser's `dragend`-then-`click` fire from navigating after a drag. Use a dedicated drag handle element where possible. (PITFALLS.md §Pitfall 6)
-- All dropdown menus that risk viewport-edge clipping must use fixed positioning from `getBoundingClientRect()` or `<Teleport to="body">`. This is a prerequisite for virtual scrolling adoption if pursued later. (UX-13, PITFALLS.md §Pitfall 7)
-- `AppIcon.vue` centralizes all SVG path data. Inline `<svg>` blocks are replaced with `<AppIcon name="..." class="..." />`. No duplicated path strings remain. (CODE-05)
-- `UX-14`: the inline "New" folder button in `AppSidebar.vue` is removed; folder creation is accessible only from the file manager.
-- A single shared `BreadcrumbBar.vue` component serves all view types — no per-view breadcrumb implementations. (UX-12)
-
-**Success Criteria** (what must be TRUE):
-1. Every zero-content context (root file list, folder, search with no results, shared-with-me, topics, audit log, cloud connections) shows a distinct `EmptyState.vue` — no plain "No items" text remains anywhere in the app
-2. Pressing `/` focuses the search bar, `Escape` closes any open modal and clears active search, `U` triggers the file upload picker, and `N` starts the new-folder input — none of these fire when a text input has focus
-3. Dragging files from the OS onto any part of the browser window (not just a drop zone) shows a full-screen overlay and uploads them on drop
-4. Every upload, delete, share, revoke, and rename action produces a toast notification that auto-dismisses after 4 seconds and does not block interaction with the page
-5. All views display a breadcrumb rendered by a single shared component; the breadcrumb reflects the full navigation path and updates on every route change
-**Plans**: 12 plans (6 waves)
-
-**Wave 0** — Foundation components + xfail test stubs (parallel)
-
-- [x] 10-01-PLAN.md — AppIcon.vue + tests (CODE-05 foundation)
-- [x] 10-02-PLAN.md — EmptyState.vue + tests (UX-01 foundation)
-- [x] 10-03-PLAN.md — BreadcrumbBar.vue + tests (UX-12 foundation)
-- [x] 10-04-PLAN.md — Toast store + ToastContainer.vue + App.vue mount + tests (UX-10 foundation)
-- [x] 10-05-PLAN.md — Wave 0 xfail test stubs for UX-02..09, UX-11, UX-13, UX-14
-
-**Wave 1** *(blocked on Wave 0 foundation components)* — Wire EmptyState, skeletons, BreadcrumbBar, UX-14, toast call sites (parallel)
-
-- [x] 10-06-PLAN.md — StorageBrowser + FileManagerView + CloudFolderView wiring (skeleton, EmptyState, BreadcrumbBar swap, FolderBreadcrumb deletion, toast call sites) — UX-02, UX-01 (storage), UX-10 (file actions), UX-12 (file manager)
-- [x] 10-07-PLAN.md — AppSidebar wiring (skeleton, EmptyState micro, UX-14 removal) — UX-03, UX-01 (sidebar), UX-14
-- [x] 10-08-PLAN.md — Admin views + Settings + SharedView + CloudStorageView (skeleton, EmptyState, BreadcrumbBar static segments) — UX-04, UX-01 (remaining), UX-12 (admin)
-
-**Wave 2** *(blocked on Wave 1)* — Keyboard shortcuts
-
-- [x] 10-09-PLAN.md — Global keydown in App.vue + ref chain through FileManagerView/StorageBrowser/DropZone/SearchBar — UX-05, UX-06, UX-07, UX-08
-
-**Wave 3** *(blocked on Wave 2)* — OS drag overlay
-
-- [x] 10-10-PLAN.md — OsDragOverlay.vue + App.vue mount + FileManagerView.handleOsDrop — UX-09
-
-**Wave 4** *(blocked on Waves 1-3)* — Drag-to-move completion + dropdown clipping fixes
-
-- [x] 10-11-PLAN.md — Click-after-drag guard in StorageBrowser + Teleport-based folder picker (StorageBrowser, DocumentCard) + FolderRow three-dot menu — UX-11, UX-13
-
-**Wave 5** *(blocked on Wave 4)* — SVG centralization across the codebase
-
-- [x] 10-12-PLAN.md — Replace all inline `<svg>` blocks in ~29 files with `<AppIcon name="..." class="..." />` — CODE-05
-**UI hint**: yes
-
----
-
-### Phase 11: Visual Design, Responsive Layout & Cleanup
-
-**Goal**: Every component uses the Tailwind spacing scale and typography system consistently, form elements have cross-browser baseline styling, interactive elements have consistent hover/focus states, the layout adapts cleanly to mobile viewports with a hamburger-toggled sidebar drawer, dead code is deleted, and bundle size is measured before and after.
-**Depends on**: Phase 10
-**Requirements**: VISUAL-01, VISUAL-02, VISUAL-03, VISUAL-04, RESP-01, RESP-02, RESP-03, RESP-04, RESP-05, CODE-07, PERF-02, PERF-03
-
-**Implementation notes:**
-- Sidebar responsive behavior: below `lg` (1024px) the sidebar is hidden; a hamburger button in a mobile-only header toggles a slide-in overlay drawer with `translate-x-0 / -translate-x-full` transition. Sidebar open/closed state lives in a Pinia store or `App.vue` ref — not in `AppSidebar`'s own `data()`. (PITFALLS.md §Pitfall 8)
-- The admin layout needs the same responsive treatment as the user layout — admin sidebar hidden on mobile, hamburger shows the admin nav drawer. (RESP-05)
-- All route components not on the critical render path must be lazy-loaded with `() => import(...)`. Admin views are explicitly lazy-loaded. (PERF-03)
-- `PERF-02` requires two Vite bundle reports committed to `.planning/`: one measured before optimizations (taken at start of this phase) and one after all work is complete (taken at end).
-- `CODE-07` dead-code deletion sweeps all unreferenced files, components, stores, and unused imports. Deletion happens after all other changes in this phase are complete — delete only what is confirmed unreferenced after all additions.
-- `VISUAL-02` requires the `@tailwindcss/forms` plugin (already listed in PERF-01) to be configured in `tailwind.config.js`.
-- `RESP-02`: `StorageBrowser`'s grid hides the Size column below `md` and Modified below `sm`. Icon, name, and actions are always visible.
-- `RESP-03`: inline icon action buttons have minimum 36×36px touch target below `md`.
-- `RESP-04`: all modal dialogs are scrollable on viewports below 640px.
-
-**Success Criteria** (what must be TRUE):
-1. At 375px viewport width, the app is fully usable: the sidebar is hidden, the hamburger opens an overlay drawer, the document list shows only icon/name/actions columns, and all touch targets are at least 36×36px
-2. All form inputs, selects, textareas, checkboxes, and radio buttons have consistent cross-browser styling with no browser-default rendering differences visible between Chrome, Firefox, and Safari
-3. Every button, card row, and interactive link has a visible `focus-visible:` ring and a distinct hover state; no interactive element is style-identical in focused and unfocused states
-4. No arbitrary pixel value (`px-[13px]`, `style="margin: 5px"`, etc.) appears in any template; all spacing is from the Tailwind scale
-5. Two bundle analysis reports are committed to `.planning/` — one baseline and one post-optimization; all non-initial-render routes are lazy-loaded and appear as separate chunks in the report
-**Plans**: TBD
-**UI hint**: yes
-
----
-
-## v0.2 Progress Table
-
-| Phase | Plans Complete | Status | Completed |
-|-------|----------------|--------|-----------|
-| 8. Stack Upgrade & Backend Decomposition | 4/8 | In Progress|  |
-| 9. Admin Panel Rearchitecture | 5/5 | Complete    | 2026-06-13 |
-| 10. UX & Interaction | 13/13 | Complete   | 2026-06-16 |
-| 11. Visual Design, Responsive Layout & Cleanup | 0/TBD | Not started | — |
-
----
-
-## Progress Table
-
-| Phase | Plans Complete | Status | Completed |
-|-------|----------------|--------|-----------|
-| 1. Infrastructure Foundation | 5/5 | Complete | 2026-05-22 |
-| 2. Users & Authentication | 6/6 | Complete   | 2026-06-01 |
-| 3. Document Migration & Multi-User Isolation | 5/5 | Complete | 2026-05-25 |
-| 4. Folders, Sharing, Quotas & Document UX | 9/9 | Complete | 2026-05-28 |
-| 5. Cloud Storage Backends | 12/12 | Complete | 2026-05-30 |
-| 6. Performance & Production Hardening | 6/6 | Complete | 2026-05-30 |
-| 6.1. Close v1.0 audit gaps | 2/2 | Complete | 2026-05-30 |
-| 6.2. Close v1 sharing + cloud-delete + CSV export gaps | 5/5 | Complete   | 2026-05-31 |
-| 7. Redo and optimize LLM integration | 5/5 | Complete | 2026-06-05 |
-| 7.1. Security: session revocation on privilege change (CR-01..03) | 0/2 | Planned | — |
-| 7.2. Security: JTI claim + Redis access-token revocation | 3/3 | Complete   | 2026-06-05 |
-| 7.3. Security: ES256 algorithm upgrade | 3/3 | Complete   | 2026-06-06 |
-| 7.4. Security: token fingerprinting / token binding | 2/2 | Complete | 2026-06-06 |
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 8. Stack Upgrade & Backend Decomposition | v0.2 | 8/8 | Complete | 2026-06-12 |
+| 9. Admin Panel Rearchitecture | v0.2 | 5/5 | Complete | 2026-06-13 |
+| 10. UX & Interaction | v0.2 | 13/13 | Complete | 2026-06-16 |
+| 11. Visual Design, Responsive Layout & Cleanup | v0.2 | 7/7 | Complete | 2026-06-17 |
+| 1. Infrastructure Foundation | v0.1 | 5/5 | Complete | 2026-05-22 |
+| 2. Users & Authentication | v0.1 | 6/6 | Complete | 2026-06-01 |
+| 3. Document Migration & Multi-User Isolation | v0.1 | 5/5 | Complete | 2026-05-25 |
+| 4. Folders, Sharing, Quotas & Document UX | v0.1 | 9/9 | Complete | 2026-05-28 |
+| 5. Cloud Storage Backends | v0.1 | 12/12 | Complete | 2026-05-30 |
+| 6. Performance & Production Hardening | v0.1 | 6/6 | Complete | 2026-05-30 |
+| 6.1. Close v1.0 audit gaps | v0.1 | 2/2 | Complete | 2026-05-30 |
+| 6.2. Close v1 sharing + cloud-delete + CSV export gaps | v0.1 | 5/5 | Complete | 2026-05-31 |
+| 7. Redo and optimize LLM integration | v0.1 | 5/5 | Complete | 2026-06-05 |
+| 7.1. Security: session revocation on privilege change | v0.1 | 2/2 | Complete | 2026-06-08 |
+| 7.2. Security: JTI claim + Redis access-token revocation | v0.1 | 3/3 | Complete | 2026-06-05 |
+| 7.3. Security: ES256 algorithm upgrade | v0.1 | 3/3 | Complete | 2026-06-06 |
+| 7.4. Security: token fingerprinting / token binding | v0.1 | 2/2 | Complete | 2026-06-06 |

.planning/STATE.md

@@ -1,32 +1,29 @@
 ---
 gsd_state_version: 1.0
 milestone: v0.2
-milestone_name: Phases
-current_phase: 10
-status: executing
-last_updated: "2026-06-16T17:05:11.592Z"
-last_activity: 2026-06-16 -- Phase 10 execution started
+milestone_name: UI Overhaul and Optimization
+current_phase: 11
+status: complete
+last_updated: "2026-06-17"
+last_activity: 2026-06-17 -- v0.2 milestone archived
 progress:
   total_phases: 4
-  completed_phases: 2
-  total_plans: 32
-  completed_plans: 25
-  percent: 50
+  completed_phases: 4
+  total_plans: 33
+  completed_plans: 33
+  percent: 100
 ---
 
 # Project State
 
 **Project:** DocuVault
-**Status:** Executing Phase 10
-**Current Phase:** 10
-**Last Updated:** 2026-06-16
+**Status:** v0.2 milestone complete — ready for next milestone
+**Last Updated:** 2026-06-17
 
 ## Current Position
 
-Phase: 10 (ux-interaction) — EXECUTING
-Plan: 1 of 13
-Status: Executing Phase 10
-Last activity: 2026-06-16 -- Phase 10 execution started
+Milestone v0.2 shipped 2026-06-17. All 4 phases complete, 40/40 requirements satisfied.
+Next action: `/gsd:new-milestone` to define v0.3
 
 ## Phase Status
 
@@ -34,17 +31,17 @@ Last activity: 2026-06-16 -- Phase 10 execution started
 |-------|-------------|--------|
 | 8. Stack Upgrade & Backend Decomposition | PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08 | **Complete (8/8 plans)** |
 | 9. Admin Panel Rearchitecture | ADMIN-08..12, CODE-06, CODE-09 | **Complete (5/5 plans)** |
-| 10. UX & Interaction | UX-01..14, CODE-05 | **Complete (12/12 plans)** |
-| 11. Visual Design, Responsive Layout & Cleanup | VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, PERF-03 | **Planned (0/6 plans)** |
+| 10. UX & Interaction | UX-01..14, CODE-05 | **Complete (13/13 plans)** |
+| 11. Visual Design, Responsive Layout & Cleanup | VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, PERF-03 | **Complete (7/7 plans)** |
 
 ## Performance Metrics
 
 | Metric | Value |
 |---|---|
-| Phases complete | 3 / 4 |
-| Requirements mapped | 40 / 40 |
-| Plans written | 96 |
-| Plans complete | 90 |
+| Phases complete | 4 / 4 |
+| Requirements satisfied | 40 / 40 |
+| Plans complete | 33 / 33 |
+| Tests at close | 277 |
 
 ## Accumulated Context
 
@@ -67,8 +64,8 @@ Last activity: 2026-06-16 -- Phase 10 execution started
 ### Roadmap Evolution
 
 - v0.1 completed: all 7 foundation phases + security hardening (2026-06-06)
-- v0.2 started: UI overhaul, code quality, admin panel rearchitecture (2026-06-07)
-- v0.2 roadmap defined: 4 phases, 40 requirements, phases 8–11 (2026-06-07)
+- v0.2 completed: UI overhaul, admin panel rearchitecture, responsive layout, codebase quality (2026-06-17)
+- v0.2 archived to `.planning/milestones/v0.2-ROADMAP.md`
 
 ### Open Questions
 
@@ -84,7 +81,7 @@ _Updated at each phase transition._
 
 | Field | Value |
 |---|---|
-| Last session | 2026-06-13 — Phase 9 complete; UAT 9/9 passed |
-| Next action | /gsd:execute-phase 11 plan 11-01 |
+| Last session | 2026-06-17 — v0.2 milestone archived |
+| Next action | /gsd:new-milestone to define v0.3 |
 | Pending decisions | None |
 | Resume file | None |

.planning/milestones/v0.2-MILESTONE-AUDIT.md

@@ -0,0 +1,103 @@
+---
+milestone: v0.2
+name: Phases
+status: passed
+audited_at: 2026-06-17
+remediated_at: 2026-06-17
+phase_count: 4
+completed_phases: 4
+requirements_total: 40
+requirements_satisfied: 40
+requirements_partial: 0
+requirements_missing: 0
+nyquist_compliant_phases: 4
+nyquist_partial_phases: 0
+integration_check:
+  status: passed
+  mode: inline_fallback
+  note: "gsd-integration-checker spawn failed in Codex runtime with child model resolution error; integration was checked inline from phase artifacts and source wiring."
+blocking_gaps: []
+---
+
+# v0.2 Milestone Audit
+
+## Verdict
+
+Milestone v0.2 now has complete gate evidence across all four phases. The original audit found missing or stale closeout artifacts; those gaps were remediated on 2026-06-17.
+
+Recommended route: archive/complete the milestone when ready.
+
+## Audit Method
+
+The workflow integration-checker subagent could not be spawned in this Codex runtime because child model resolution failed. The integration step was completed inline by cross-checking phase summaries, verification files, validation/security artifacts, requirements traceability, and source wiring.
+
+## Phase Gate Summary
+
+| Phase | Verification | Validation | UAT | Security | Audit result |
+|---|---:|---:|---:|---:|---|
+| 08 Stack Upgrade / Backend Decomposition | Passed, 6/6 | Complete | Complete | Verified | Complete |
+| 09 Admin Panel Rearchitecture | Human needed, 5/5 | Complete | Complete | Verified | Acceptable with ADMIN-09 decision noted |
+| 10 UX Interaction | Passed, 15/15 | Complete | Resolved | Verified | Complete |
+| 11 Visual / Responsive Cleanup | Passed, 12/12 | Complete | Resolved | Complete | Complete |
+
+## Blocking Gaps
+
+All blocking gaps from the initial audit are resolved.
+
+## Remediation Completed
+
+1. Phase 08 verification was reconstructed in `08-VERIFICATION.md`.
+2. Phase 10 security gate was reconstructed in `10-SECURITY.md`.
+3. Phase 11 post-11-07 UAT/validation/verification closure was recorded in `11-UAT.md`, `11-VALIDATION.md`, and `11-VERIFICATION.md`.
+4. `REQUIREMENTS.md` traceability was updated for all completed v0.2 requirements.
+5. ADMIN-09 was aligned with the accepted Phase 09 D-06 decision: admin accounts are administration-only and no "Back to app" link is rendered.
+6. `npm audit --audit-level=high` high-severity esbuild finding was closed by upgrading frontend Vite to `^8.0.16`.
+
+## Requirement Coverage
+
+| Phase | Requirements | Satisfied | Partial | Notes |
+|---|---:|---:|---:|---|
+| 08 | 6 | 6 | 0 | `08-VERIFICATION.md` now exists and verifies all Phase 8 v0.2 requirements |
+| 09 | 7 | 7 | 0 | ADMIN-09 text now matches accepted D-06 admin-only decision |
+| 10 | 15 | 15 | 0 | Verification passed; requirements traceability updated |
+| 11 | 12 | 12 | 0 | Plan 11-07 mobile UAT closure is reflected in UAT, validation, and verification artifacts |
+
+Strict audit score: 40/40 requirements satisfied, 0 partial, 0 missing.
+
+## Integration Findings
+
+The milestone's cross-phase wiring appears coherent:
+
+- Phase 08 backend decomposition preserved route/module behavior according to summaries and green tests.
+- Phase 08 frontend client barrel exports avoided consumer churn.
+- Phase 09 admin routing uses the admin layout and matched-route guard pattern.
+- Phase 10 shared UX components feed into Phase 11 responsive cleanup.
+- `StorageBrowser.vue` remains the single shared file browser used by local and cloud file views.
+
+Previously identified integration risks are resolved:
+
+- Phase 08 now has the canonical verification artifact.
+- Phase 10 now has the canonical security artifact.
+- Phase 11 post-fix evidence loop is closed after plan 11-07.
+- ADMIN-09 is explicitly aligned with decision D-06.
+
+## Nyquist Review
+
+| Phase | Nyquist status | Evidence |
+|---|---|---|
+| 08 | Compliant | `08-VALIDATION.md` marks `nyquist_compliant: true` |
+| 09 | Compliant | `09-VALIDATION.md` marks `nyquist_compliant: true` |
+| 10 | Compliant | `10-VALIDATION.md` marks `nyquist_compliant: true` |
+| 11 | Compliant | `11-VALIDATION.md` marks `nyquist_compliant: true` after plan 11-07 closure |
+
+## Remediation Checklist
+
+1. [x] Run or reconstruct Phase 08 verification and create `08-VERIFICATION.md`.
+2. [x] Run the Phase 10 security gate and create `10-SECURITY.md`.
+3. [x] Re-run Phase 11 UAT/validation after plan 11-07 and update `11-UAT.md`, `11-VALIDATION.md`, and `11-VERIFICATION.md` as needed.
+4. [x] Update `REQUIREMENTS.md` traceability once the above artifacts exist.
+5. [x] Decide whether ADMIN-09 should remain a documented D-06 override or be edited to remove the "Back to app" requirement.
+
+## Archive Decision
+
+Milestone v0.2 is ready for archival/closeout from this audit's perspective.

.planning/milestones/v0.2-REQUIREMENTS.md

@@ -0,0 +1,114 @@
+# DocuVault v0.2 Requirements — Archive
+
+**Milestone:** v0.2 — UI Overhaul and Optimization
+**Archived:** 2026-06-17
+**Total requirements:** 40 — all satisfied
+
+---
+
+## CODE — Codebase Quality
+
+- [x] **CODE-01**: Backend `api/admin.py` decomposed into `api/admin/` package — Phase 8, Complete
+- [x] **CODE-02**: `api/documents.py` decomposed into `api/documents/` package — Phase 8, Complete
+- [x] **CODE-03**: `api/auth.py` decomposed into `api/auth/` package — Phase 8, Complete
+- [x] **CODE-04**: Frontend `api/client.js` decomposed into domain modules; barrel re-export — Phase 8, Complete
+- [x] **CODE-05**: All inline SVG blocks replaced with `<AppIcon name="..." />`; path data centralized — Phase 10, Complete
+- [x] **CODE-06**: Tailwind `safelist` configured for all dynamic class name patterns in `formatters.js` — Phase 9, Complete
+- [x] **CODE-07**: All unreferenced files, components, stores, and unused imports deleted — Phase 11, Complete
+- [x] **CODE-08**: No duplicated Pydantic model definitions; shared schemas in dedicated modules — Phase 8, Complete
+- [x] **CODE-09**: No WHAT comments remain; WHY-only policy enforced across all touched files — Phase 9, Complete
+
+## ADMIN — Admin Panel
+
+- [x] **ADMIN-08**: Admin panel at `/admin/*`; `AdminLayout.vue` as route component; `AdminView.vue` deleted — Phase 9, Complete
+- [x] **ADMIN-09**: Admin sidebar: Overview, Users, Quotas, AI Config, Audit Log. No "Back to app" link (D-06 decision) — Phase 9, Complete
+- [x] **ADMIN-10**: Deep-linkable URLs (`/admin/users`, `/admin/quotas`, `/admin/ai`, `/admin/audit`); back button works — Phase 9, Complete
+- [x] **ADMIN-11**: Admin overview page with user count, platform storage, doc status breakdown, last 10 audit entries — Phase 9, Complete
+- [x] **ADMIN-12**: `to.matched.some(r => r.meta.requiresAdmin)` guard on all `/admin/*` routes — Phase 9, Complete
+
+## UX — UX and Interaction
+
+- [x] **UX-01**: `EmptyState.vue` in all zero-content contexts; no plain "No items" text remains — Phase 10, Complete
+- [x] **UX-02**: `StorageBrowser` displays 5-col `animate-pulse` skeleton grid rows during loading — Phase 10, Complete
+- [x] **UX-03**: Sidebar folder tree and topics list display skeleton placeholders during loading — Phase 10, Complete
+- [x] **UX-04**: Admin user table and audit log table display skeleton table rows during loading — Phase 10, Complete
+- [x] **UX-05**: Pressing `/` when no input is focused moves focus to the search bar — Phase 10, Complete
+- [x] **UX-06**: Pressing `Escape` closes any open modal and clears active search — Phase 10, Complete
+- [x] **UX-07**: Pressing `U` when no input is focused triggers the file upload picker — Phase 10, Complete
+- [x] **UX-08**: Pressing `N` when no input is focused starts the new folder inline input — Phase 10, Complete
+- [x] **UX-09**: OS drag-onto-browser shows full-screen overlay; releasing uploads files — Phase 10, Complete
+- [x] **UX-10**: Toast notification system (auto-dismiss 4s, stacking, non-blocking) for upload/delete/share/rename — Phase 10, Complete
+- [x] **UX-11**: Drag-to-move document onto folder row with `ring-2 ring-inset ring-amber-300` drop highlight — Phase 10, Complete
+- [x] **UX-12**: Single shared `BreadcrumbBar.vue` across all views; updates on every route change — Phase 10, Complete
+- [x] **UX-13**: All dropdowns use `Teleport + getBoundingClientRect`; no viewport-edge clipping — Phase 10, Complete
+- [x] **UX-14**: Inline "New" folder button removed from `AppSidebar.vue`; folder creation in file manager only — Phase 10, Complete
+
+## VISUAL — Visual Design
+
+- [x] **VISUAL-01**: Consistent spacing scale; no arbitrary `px-[N]` values or inline `style` margins — Phase 11, Complete
+- [x] **VISUAL-02**: `@tailwindcss/forms` plugin configured; cross-browser form element baseline styling — Phase 11, Complete
+- [x] **VISUAL-03**: All interactive elements have consistent hover, `focus-visible:` rings, and active states — Phase 11, Complete
+- [x] **VISUAL-04**: Consistent typography scale: one heading size per level, one body size, one label/caption size — Phase 11, Complete
+
+## RESP — Responsive Layout
+
+- [x] **RESP-01**: Sidebar hidden below `lg` (1024px); hamburger opens slide-in overlay drawer — Phase 11, Complete
+- [x] **RESP-02**: Document list hides Size column below `md`, Modified below `sm`; compact icon toolbar below `sm` — Phase 11, Complete (11-07 gap closure)
+- [x] **RESP-03**: Inline icon action buttons ≥36×36px touch target on viewports below `md` — Phase 11, Complete
+- [x] **RESP-04**: All modal dialogs scrollable on viewports below 640px — Phase 11, Complete
+- [x] **RESP-05**: Admin layout has same responsive behavior (hamburger, drawer) as user layout — Phase 11, Complete
+
+## PERF — Performance and Stack
+
+- [x] **PERF-01**: Frontend dependencies bumped: `vue@^3.5.0`, `vite@^8.0.16`, `@vueuse/core@^14.3.0`, `sortablejs`, `@tailwindcss/forms`, `rollup-plugin-visualizer` — Phase 8, Complete
+- [x] **PERF-02**: Bundle baseline and post-optimization reports committed to `.planning/` — Phase 11, Complete (−81 kB / −30.6%)
+- [x] **PERF-03**: All non-initial-render routes lazy-loaded; admin views explicitly lazy-loaded — Phase 11, Complete
+
+---
+
+## Traceability
+
+| REQ-ID | Phase | Status |
+|--------|-------|--------|
+| PERF-01 | Phase 8 | ✓ Complete |
+| CODE-01 | Phase 8 | ✓ Complete |
+| CODE-02 | Phase 8 | ✓ Complete |
+| CODE-03 | Phase 8 | ✓ Complete |
+| CODE-04 | Phase 8 | ✓ Complete |
+| CODE-08 | Phase 8 | ✓ Complete |
+| ADMIN-08 | Phase 9 | ✓ Complete |
+| ADMIN-09 | Phase 9 | ✓ Complete (D-06: admin-only, no Back-to-app) |
+| ADMIN-10 | Phase 9 | ✓ Complete |
+| ADMIN-11 | Phase 9 | ✓ Complete |
+| ADMIN-12 | Phase 9 | ✓ Complete |
+| CODE-06 | Phase 9 | ✓ Complete |
+| CODE-09 | Phase 9 | ✓ Complete |
+| UX-01 | Phase 10 | ✓ Complete |
+| UX-02 | Phase 10 | ✓ Complete |
+| UX-03 | Phase 10 | ✓ Complete |
+| UX-04 | Phase 10 | ✓ Complete |
+| UX-05 | Phase 10 | ✓ Complete |
+| UX-06 | Phase 10 | ✓ Complete |
+| UX-07 | Phase 10 | ✓ Complete |
+| UX-08 | Phase 10 | ✓ Complete |
+| UX-09 | Phase 10 | ✓ Complete |
+| UX-10 | Phase 10 | ✓ Complete |
+| UX-11 | Phase 10 | ✓ Complete |
+| UX-12 | Phase 10 | ✓ Complete |
+| UX-13 | Phase 10 | ✓ Complete |
+| UX-14 | Phase 10 | ✓ Complete |
+| CODE-05 | Phase 10 | ✓ Complete |
+| VISUAL-01 | Phase 11 | ✓ Complete |
+| VISUAL-02 | Phase 11 | ✓ Complete |
+| VISUAL-03 | Phase 11 | ✓ Complete |
+| VISUAL-04 | Phase 11 | ✓ Complete |
+| RESP-01 | Phase 11 | ✓ Complete |
+| RESP-02 | Phase 11 | ✓ Complete |
+| RESP-03 | Phase 11 | ✓ Complete |
+| RESP-04 | Phase 11 | ✓ Complete |
+| RESP-05 | Phase 11 | ✓ Complete |
+| CODE-07 | Phase 11 | ✓ Complete |
+| PERF-02 | Phase 11 | ✓ Complete |
+| PERF-03 | Phase 11 | ✓ Complete |
+
+*All 40 requirements satisfied. Archive created 2026-06-17.*

.planning/milestones/v0.2-ROADMAP.md

@@ -0,0 +1,154 @@
+# Milestone v0.2: UI Overhaul and Optimization
+
+**Status:** ✅ SHIPPED 2026-06-17
+**Phases:** 8–11
+**Total Plans:** 33
+
+## Overview
+
+v0.2 transformed DocuVault from a feature-complete but rough alpha into a polished, production-quality web application. The milestone covered four areas: codebase quality (decomposing monolith routers, eliminating duplication, purging dead code), admin panel rearchitecture (standalone route subtree with deep-linkable views), UX & interaction (empty states, skeletons, keyboard shortcuts, OS drag-drop, toast notifications), and visual design with responsive layout (mobile sidebar, consistent spacing, form styling, bundle optimization).
+
+## Phases
+
+### Phase 8: Stack Upgrade & Backend Decomposition
+
+**Goal**: The dependency stack is current, all three backend router monoliths are split into focused sub-packages with zero URL or behavior changes, and the frontend API client is decomposed into domain modules behind a re-export barrel — the entire change is invisible to consumers and tests.
+**Depends on**: Phase 7.4 (last v0.1 phase)
+**Requirements**: PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08
+**Plans**: 8 plans (3 waves)
+
+**Wave 0** — Foundation (parallel)
+- [x] 08-01-PLAN.md — CR-01/02/03 test stubs (3 xfail stubs in test_auth.py) + Wave 0 scaffolds for regression detection
+- [x] 08-02-PLAN.md — `api/schemas.py` creation + `CloudConnectionOut` migration from admin.py (MUST precede admin split)
+
+**Wave 1** — Phase 7.1 completion (frontend only)
+- [x] 08-03-PLAN.md — `useToastStore` stub + CR test promotion + SettingsAccountTab.vue + TotpEnrollment.vue inline toast replacement
+
+**Wave 2** — Backend decomposition + frontend (parallel)
+- [x] 08-04-PLAN.md — Split `api/admin.py` → `api/admin/` package (CODE-01)
+- [x] 08-05-PLAN.md — Split `api/documents.py` → `api/documents/` package (CODE-02)
+- [x] 08-06-PLAN.md — Split `api/auth.py` → `api/auth/` package (CODE-03)
+- [x] 08-07-PLAN.md — Frontend `client.js` decomposition: utils.js + 7 domain modules + barrel rewrite (CODE-04)
+- [x] 08-08-PLAN.md — PERF-01 dependency bump + tailwind/vite config wiring + requirements.txt exact pinning
+
+**Completed:** 2026-06-12
+
+---
+
+### Phase 9: Admin Panel Rearchitecture
+
+**Goal**: The admin interface is a standalone route subtree (`/admin/*`) with its own layout component and sidebar; each admin section is deep-linkable and browser-back-button works; the `requiresAdmin` navigation guard correctly protects all child routes; and the Tailwind safelist is configured so dynamic color classes render correctly in production builds.
+**Depends on**: Phase 8
+**Requirements**: ADMIN-08, ADMIN-09, ADMIN-10, ADMIN-11, ADMIN-12, CODE-06, CODE-09
+**Plans**: 5 plans (4 waves)
+
+**Wave 1** — Foundation (parallel)
+- [x] 09-01-PLAN.md — Backend overview.py endpoint + 8 ADMIN-11 tests
+- [x] 09-02-PLAN.md — Frontend AdminLayout + AdminSidebar + AdminOverviewView + getAdminOverview API client
+
+**Wave 2**
+- [x] 09-03-PLAN.md — Extract 4 admin tab components to standalone views
+
+**Wave 3**
+- [x] 09-04-PLAN.md — Router rearchitecture (nested /admin + to.matched.some guard) + Tailwind safelist + delete AdminView.vue
+
+**Wave 4**
+- [x] 09-05-PLAN.md — CODE-09 comment purge + human checkpoint UAT
+
+**Completed:** 2026-06-13
+
+---
+
+### Phase 10: UX & Interaction
+
+**Goal**: The application communicates state clearly at every moment — empty contexts have purposeful empty states, loading transitions show structured skeletons, power users can operate keyboard-first, files can be dragged from the OS directly onto the browser, and every action produces an immediate toast confirmation.
+**Depends on**: Phase 9
+**Requirements**: UX-01 through UX-14, CODE-05
+**Plans**: 13 plans (6 waves)
+
+**Wave 0** — Foundation components + xfail test stubs (parallel)
+- [x] 10-01-PLAN.md — AppIcon.vue + tests (CODE-05 foundation)
+- [x] 10-02-PLAN.md — EmptyState.vue + tests (UX-01 foundation)
+- [x] 10-03-PLAN.md — BreadcrumbBar.vue + tests (UX-12 foundation)
+- [x] 10-04-PLAN.md — Toast store + ToastContainer.vue + App.vue mount + tests (UX-10 foundation)
+- [x] 10-05-PLAN.md — Wave 0 xfail test stubs for UX-02..09, UX-11, UX-13, UX-14
+
+**Wave 1** — Wire EmptyState, skeletons, BreadcrumbBar (parallel)
+- [x] 10-06-PLAN.md — StorageBrowser + FileManagerView + CloudFolderView wiring
+- [x] 10-07-PLAN.md — AppSidebar wiring (skeleton, EmptyState, UX-14 removal)
+- [x] 10-08-PLAN.md — Admin views + Settings + SharedView + CloudStorageView
+
+**Wave 2** — Keyboard shortcuts
+- [x] 10-09-PLAN.md — Global keydown in App.vue + ref chain through FileManagerView/StorageBrowser
+
+**Wave 3** — OS drag overlay
+- [x] 10-10-PLAN.md — OsDragOverlay.vue + App.vue mount + FileManagerView.handleOsDrop
+
+**Wave 4** — Drag-to-move + dropdown clipping fixes
+- [x] 10-11-PLAN.md — Click-after-drag guard + Teleport-based folder picker + FolderRow three-dot menu
+
+**Wave 5** — SVG centralization
+- [x] 10-12-PLAN.md — Replace all inline `<svg>` blocks with `<AppIcon name="..." />`
+
+**UAT Gap Closure**
+- [x] 10-13-PLAN.md — 6 UAT gaps closed: sidebar shimmer, search-at-root, admin sidebar isolation, keyboard dispatch fix, Escape modifier, OS drop capture phase
+
+**Completed:** 2026-06-16
+
+---
+
+### Phase 11: Visual Design, Responsive Layout & Cleanup
+
+**Goal**: Every component uses the Tailwind spacing scale and typography system consistently, form elements have cross-browser baseline styling, interactive elements have consistent hover/focus states, the layout adapts cleanly to mobile viewports with a hamburger-toggled sidebar drawer, dead code is deleted, and bundle size is measured before and after.
+**Depends on**: Phase 10
+**Requirements**: VISUAL-01 through VISUAL-04, RESP-01 through RESP-05, CODE-07, PERF-02, PERF-03
+**Plans**: 7 plans (5 waves + 1 UAT gap closure)
+
+- [x] 11-01-PLAN.md — Bundle baseline + Vite analyzer wiring + lazy-load admin routes (PERF-02, PERF-03)
+- [x] 11-02-PLAN.md — Tailwind forms plugin + form element baseline styling (VISUAL-02)
+- [x] 11-03-PLAN.md — Responsive shells and storage rows (RESP-01, RESP-02)
+- [x] 11-04-PLAN.md — Mobile-safe modals and form baseline verification (RESP-04, RESP-05)
+- [x] 11-05-PLAN.md — Visual consistency pass — typography, focus-visible, hover/active states (VISUAL-01, VISUAL-03, VISUAL-04, RESP-03)
+- [x] 11-06-PLAN.md — Dead-code sweep + bundle final measurement (CODE-07, PERF-02 post-opt)
+- [x] 11-07-PLAN.md — Mobile storage toolbar compact icon controls (RESP-02, RESP-03 gap closure)
+
+**Completed:** 2026-06-17
+
+---
+
+## Milestone Summary
+
+**Key Decisions:**
+
+- Options API preserved in v0.2 refactor — Composition API migration is scope-creep for a UX milestone
+- Admin panel as standalone route subtree — AdminView.vue as tabs-on-user-layout is architecturally wrong
+- `client.js` barrel re-export pattern — zero consumer churn; all 35+ import sites stay unchanged
+- Sub-routers carry NO prefix — parent `include_router` propagates prefix; sub-router with prefix causes double-segment URLs
+- FastAPI 0.128+ empty-path restriction — `@router.get("")` on sub-router with empty include prefix raises FastAPIError
+- `to.matched.some()` for requiresAdmin guard — Vue Router 4 does not inherit meta to children; direct `to.meta` check is a security regression
+- Vite 6→8 upgrade — resolved moderate CVEs (CVE-2026-39363/39364); npm audit clean
+- AdminLayout as route component, not App.vue branch — router resolves AdminLayout as /admin component; its router-view renders children
+- Tailwind safelist with regex patterns — dynamic color classes (sky=OneDrive, amber=admin audit badges) are tree-shaken without safelist
+
+**Issues Resolved:**
+
+- Admin panel auth guard was checking `to.meta.requiresAdmin` directly (Vue Router 4 doesn't inherit meta to children) — fixed to `to.matched.some()`
+- Three-dot dropdown menus clipped by scroll containers — fixed with Teleport + getBoundingClientRect positioning
+- Admin views loaded synchronously — all lazy-loaded, reducing initial bundle by 81 kB (−30.6%)
+- Inline SVG duplicated path data in 66 instances — centralized in AppIcon.vue
+- Mobile toolbar overflow below 550px — compact icon controls added in 11-07
+
+**Issues Deferred:**
+
+- Virtual scrolling — quota cap (100 MB/user) limits lists to hundreds of items; v-for sufficient
+- Dark mode — coherent color token system must exist first
+- Folder reordering by drag — requires persistent `position` column in DB
+- Composition API migration — separate milestone
+
+**Technical Debt Incurred:**
+
+- Options API retained throughout — intentional deferral; next milestone may begin Composition API migration
+
+---
+
+*For current project status, see .planning/ROADMAP.md*

.planning/milestones/v0.2-phases/08-stack-upgrade-backend-decomposition/08-VERIFICATION.md

@@ -0,0 +1,71 @@
+---
+phase: 08-stack-upgrade-backend-decomposition
+verified: 2026-06-17T11:15:00Z
+status: passed
+score: 6/6 v0.2 requirements verified
+overrides_applied: 0
+sources:
+  - 08-VALIDATION.md
+  - 08-UAT.md
+  - 08-SECURITY.md
+  - 08-01-SUMMARY.md
+  - 08-02-SUMMARY.md
+  - 08-03-SUMMARY.md
+  - 08-04-SUMMARY.md
+  - 08-05-SUMMARY.md
+  - 08-06-SUMMARY.md
+  - 08-07-SUMMARY.md
+  - 08-08-SUMMARY.md
+---
+
+# Phase 8: Stack Upgrade & Backend Decomposition Verification Report
+
+**Phase Goal:** Split the largest backend and frontend modules into focused packages without changing public routes, client imports, auth behavior, storage invariants, or test outcomes.
+
+**Status:** passed
+
+## Goal Achievement
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| CODE-01 | VERIFIED | Admin router decomposed into `backend/api/admin/`; `08-VALIDATION.md` maps this to `pytest tests/test_admin_api.py -x`; Phase 8 UAT confirms all admin endpoints preserve route paths and access controls. |
+| CODE-02 | VERIFIED | Documents router decomposed into `backend/api/documents/`; `08-VALIDATION.md` maps this to `pytest tests/test_documents.py -x`; Phase 8 UAT confirms upload/list/detail/delete workflow passes. |
+| CODE-03 | VERIFIED | Auth router decomposed into `backend/api/auth/`; `08-VALIDATION.md` maps this to `pytest tests/test_auth.py -x`; Phase 8 UAT confirms register/login/refresh/logout and session revocation. |
+| CODE-04 | VERIFIED | Frontend API client split into domain modules while preserving `client.js` barrel exports; Phase 8 UAT confirms cloud connection API consumers still work with zero consumer-file churn. |
+| CODE-08 | VERIFIED | Shared schemas/validators extracted; `CloudConnectionOut` is defined once in `backend/api/schemas.py`; `08-SECURITY.md` records duplicate-definition and credential-leak checks as closed. |
+| PERF-01 | VERIFIED | Frontend dependency stack upgraded; Phase 8 UAT recorded Vite 6.4.3 build success, and milestone remediation later moved Vite to 8.0.16 to clear the 2026 esbuild high-severity audit finding. |
+
+## Required Artifacts
+
+| Artifact | Status | Notes |
+|---|---|---|
+| `08-VALIDATION.md` | VERIFIED | `nyquist_compliant: true`; all Phase 8 requirements covered by automated commands or static checks. |
+| `08-UAT.md` | VERIFIED | 7/7 UAT checks passed, including cold start, auth, document management, admin, cloud storage, session revocation, and Vite build. |
+| `08-SECURITY.md` | VERIFIED | `threats_open: 0`; 45/45 threats closed or accepted. |
+| Plan summaries 08-01 through 08-08 | VERIFIED | All implementation summaries exist and provide traceable completion evidence. |
+
+## Behavioral Spot-Checks
+
+| Check | Evidence | Status |
+|---|---|---|
+| Backend route regression | `08-VALIDATION.md`: admin/documents/auth targeted suites pass; combined URL regression suite records 58 passed. | PASS |
+| Full backend suite | `08-VALIDATION.md`: `pytest -v` recorded 405 passed, 6 skipped, 7 xfailed. | PASS |
+| Frontend smoke | `08-VALIDATION.md`: `npm test` recorded 136/136 passed. | PASS |
+| Production build | `08-UAT.md`: original Phase 8 build produced `frontend/dist/` with exit 0; milestone remediation re-ran the current Vite 8 build successfully. | PASS |
+
+## Security Review
+
+Phase 8 security is already verified by `08-SECURITY.md`:
+
+- Admin sub-router handlers retain `Depends(get_current_admin)`.
+- Document endpoints preserve owner checks and filename/path-separator validation.
+- Auth sub-router preserves refresh rotation, session revocation, JTI/fingerprint behavior, and audit logging.
+- Frontend client split keeps tokens in Pinia memory only.
+- No new unmanaged supply-chain risk remains open.
+
+## Gaps Summary
+
+No Phase 8 verification gaps remain.
+
+_Verified: 2026-06-17T11:15:00Z_
+_Verifier: Codex (milestone audit remediation)_

.planning/milestones/v0.2-phases/10-ux-interaction/10-13-PLAN.md

@@ -0,0 +1,393 @@
+---
+phase: 10-ux-interaction
+plan: 13
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - frontend/src/components/ui/TreeItem.vue
+  - frontend/src/components/storage/StorageBrowser.vue
+  - frontend/src/App.vue
+  - frontend/src/components/documents/SearchBar.vue
+  - frontend/src/components/layout/OsDragOverlay.vue
+  - frontend/src/__tests__/keyboard.test.js
+  - frontend/src/components/ui/__tests__/TreeItem.test.js
+  - frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js
+autonomous: true
+requirements: [UX-02, UX-03, UX-05, UX-06, UX-07, UX-08, UX-09]
+gap_closure: true
+
+must_haves:
+  truths:
+    - "Sidebar Cloud/Folder sections show animated shimmer rows while async data loads — no 'Loading…' text visible"
+    - "Admin routes (/admin/*) render with no AppSidebar — AdminLayout is the sole layout component"
+    - "Pressing '/', 'U', or 'N' in the file manager dispatches to the actual FileManagerView instance — not a RouterView proxy"
+    - "Pressing Escape in the search input clears the field and preserves focus — no browser-native blur"
+    - "Dropping an OS file on the drag overlay triggers upload — capture-phase window listener fires before folder-row handlers"
+    - "Search bar and sort controls are visible at the root of both local and cloud file browsers"
+  artifacts:
+    - path: "frontend/src/components/ui/TreeItem.vue"
+      provides: "Three animate-pulse shimmer rows in the v-if='loading' branch"
+      contains: "animate-pulse"
+    - path: "frontend/src/components/storage/StorageBrowser.vue"
+      provides: "showSearch computed returns true for mode === 'local' OR mode === 'cloud'"
+    - path: "frontend/src/App.vue"
+      provides: "Third template branch for admin routes (no AppSidebar); getFileManagerInstance() via matched.find for keyboard dispatch"
+    - path: "frontend/src/components/documents/SearchBar.vue"
+      provides: "@keydown.escape.prevent.stop suppresses browser native blur on type='search'"
+    - path: "frontend/src/components/layout/OsDragOverlay.vue"
+      provides: "window drop listener registered with capture=true; removeEventListener also passes true"
+  key_links:
+    - from: "frontend/src/App.vue (onKeydown)"
+      to: "FileManagerView.focusSearch / triggerUpload / startNewFolder"
+      via: "router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default"
+      pattern: "instances\\.default"
+    - from: "frontend/src/components/layout/OsDragOverlay.vue"
+      to: "window drop event"
+      via: "addEventListener('drop', handler, true)"
+      pattern: "addEventListener.*drop.*true"
+---
+
+<objective>
+Close all 6 UAT gaps from 10-UAT.md that block Phase 10 sign-off: sidebar shimmer (Gap 1), search-at-root visibility (Gap 2), admin sidebar bleed (Gap 3), keyboard shortcuts broken by RouterView proxy (Gap 4 — covers tests 11, 12, 13), Escape-breaks-search (Gap 5), and OS drag-drop not uploading (Gap 6).
+
+Purpose: Phase 10 is recorded complete in ROADMAP.md but UAT (10-UAT.md) shows 9 issues with 6 distinct root causes diagnosed. These targeted fixes close all 6 causes with minimal code change, restoring full UAT pass.
+
+Output: Five production files modified, three test files added. No new dependencies. No regressions.
+</objective>
+
+<execution_context>
+@/Users/nik/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/nik/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@/Users/nik/Documents/Progamming/document_scanner/.planning/PROJECT.md
+@/Users/nik/Documents/Progamming/document_scanner/.planning/ROADMAP.md
+@/Users/nik/Documents/Progamming/document_scanner/.planning/STATE.md
+@/Users/nik/Documents/Progamming/document_scanner/.planning/phases/10-ux-interaction/10-UAT.md
+
+<interfaces>
+<!-- Key contracts the executor needs. Extracted from codebase. No codebase exploration needed. -->
+
+From frontend/src/App.vue (current full state — relevant sections):
+```html
+<!-- Template — only two branches today: -->
+<AuthLayout v-if="route.meta.layout === 'auth'" />
+<div v-else class="flex h-screen overflow-hidden">
+  <AppSidebar />
+  <main class="flex-1 overflow-y-auto">
+    <router-view ref="routeViewRef" />   <!-- resolves to RouterView proxy, NOT FileManagerView -->
+  </main>
+</div>
+<ToastContainer />
+<OsDragOverlay @files-dropped="onOsFilesDropped" />
+```
+```js
+// script setup
+import { ref, onMounted, onUnmounted } from 'vue'
+import { useRoute } from 'vue-router'
+const route = useRoute()
+const routeViewRef = ref(null)         // ← remove this
+
+function onOsFilesDropped(files) {
+  routeViewRef.value?.handleOsDrop?.(files)  // ← fix to use getFileManagerInstance()
+}
+function onKeydown(e) {
+  // guard: INPUT/TEXTAREA/SELECT/contentEditable + dialog check omitted here
+  routeViewRef.value?.focusSearch?.()    // line 37 ← fix
+  routeViewRef.value?.clearSearch?.()    // line 40 ← fix
+  routeViewRef.value?.triggerUpload?.()  // line 43 ← fix
+  routeViewRef.value?.startNewFolder?.() // line 46 ← fix
+}
+```
+
+From frontend/src/router/index.js — admin route meta:
+```js
+{
+  path: '/admin',
+  component: () => import('../layouts/AdminLayout.vue'),
+  meta: { requiresAdmin: true },   // only on parent; children resolved via matched.some()
+  children: [/* AdminOverviewView, AdminUsersView, AdminQuotasView, AdminAiView, AdminAuditView */]
+}
+```
+
+From frontend/src/components/ui/TreeItem.vue — loading branch to replace (lines 48-52):
+```html
+<div
+  v-if="loading"
+  class="text-xs text-gray-400 py-1"
+  :style="{ paddingLeft: `${(depth + 1) * 12 + 8}px` }"
+>
+  Loading…
+</div>
+```
+
+Shimmer pattern to replicate (from AppSidebar.vue lines 60-64):
+```html
+<div v-if="loadingRoots" class="pl-7 py-1 space-y-1">
+  <div v-for="n in 3" :key="`sk-f-${n}`" class="flex items-center gap-2 py-1">
+    <div class="w-4 h-4 bg-gray-100 rounded animate-pulse shrink-0"></div>
+    <div class="h-3 bg-gray-100 rounded animate-pulse" :style="{ width: (50 + n * 15) + 'px' }"></div>
+  </div>
+</div>
+```
+
+From frontend/src/components/storage/StorageBrowser.vue line 287:
+```js
+const showSearch = computed(() => props.mode === 'local' && props.breadcrumb.length > 0)
+// TARGET STATE:
+const showSearch = computed(() => props.mode === 'local' || props.mode === 'cloud')
+```
+
+From frontend/src/components/documents/SearchBar.vue line 11:
+```html
+@keydown.escape="emit('update:modelValue', '')"
+<!-- TARGET STATE: -->
+@keydown.escape.prevent.stop="emit('update:modelValue', '')"
+```
+
+From frontend/src/components/layout/OsDragOverlay.vue (Options API — lines 52-63):
+```js
+mounted() {
+  window.addEventListener('dragenter', this.onDragEnter)
+  window.addEventListener('dragleave', this.onDragLeave)
+  window.addEventListener('dragover', this.onDragOver)
+  window.addEventListener('drop', this.onDrop)            // ← bubble phase; must become capture
+},
+beforeUnmount() {
+  window.removeEventListener('dragenter', this.onDragEnter)
+  window.removeEventListener('dragleave', this.onDragLeave)
+  window.removeEventListener('dragover', this.onDragOver)
+  window.removeEventListener('drop', this.onDrop)         // ← must match with true
+}
+```
+
+From frontend/src/views/FileManagerView.vue defineExpose (lines 190-196):
+```js
+// These ARE correct — all methods are exposed. The problem is App.vue never reaches this instance.
+defineExpose({
+  focusSearch: () => browserRef.value?.focusSearch?.(),
+  triggerUpload: () => browserRef.value?.triggerUpload?.(),
+  startNewFolder: () => browserRef.value?.startNewFolder?.(),
+  clearSearch: () => browserRef.value?.clearSearch?.(),
+  handleOsDrop: (files) => onFilesSelected({ files, autoClassify: true }),
+})
+```
+
+From frontend/src/__tests__/keyboard.test.js (existing structure):
+Uses mountFileManager() helper, vi.mock('../api/client.js', ...), vi.mock('../stores/auth.js', ...),
+vi.mock('../stores/topics.js', ...), setActivePinia(createPinia()), createRouter+createMemoryHistory.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Sidebar shimmer rows (TreeItem.vue) and search-at-root (StorageBrowser.vue)</name>
+  <files>
+    frontend/src/components/ui/TreeItem.vue
+    frontend/src/components/storage/StorageBrowser.vue
+  </files>
+  <action>
+    TreeItem.vue — replace the v-if="loading" div (lines 48-52) with a shimmer block. The replacement wraps three shimmer rows in a single container div. Apply the indent :style on the container (same binding the removed div had: `{ paddingLeft: \`\${(depth + 1) * 12 + 8}px\` }`). The container also gets `class="py-1 space-y-1"`. Each of the three inner rows uses `class="flex items-center gap-2 py-1"` and contains two children:
+    - Icon placeholder: `class="w-4 h-4 bg-gray-100 rounded animate-pulse shrink-0"`
+    - Text placeholder: `class="h-3 bg-gray-100 rounded animate-pulse"` with `:style="{ width: (50 + n * 15) + 'px' }"`
+    Use `v-for="n in 3"` with `:key="\`sk-t-\${n}\`"` on the inner row div.
+    Do not change any other branch (v-else-if loadError, v-else-if children.length===0, slot children) or any script section.
+
+    StorageBrowser.vue — change line 287 only. Change:
+      `const showSearch = computed(() => props.mode === 'local' && props.breadcrumb.length > 0)`
+    to:
+      `const showSearch = computed(() => props.mode === 'local' || props.mode === 'cloud')`
+    No template changes needed — SearchBar and SortControls already share v-if="showSearch".
+  </action>
+  <verify>
+    <automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep -c "animate-pulse" src/components/ui/TreeItem.vue && grep "showSearch" src/components/storage/StorageBrowser.vue | grep "cloud"</automated>
+  </verify>
+  <done>
+    - `grep -c "animate-pulse" src/components/ui/TreeItem.vue` returns at least 2
+    - `grep -c "Loading" src/components/ui/TreeItem.vue` returns 0
+    - `grep "showSearch" src/components/storage/StorageBrowser.vue` contains `props.mode === 'cloud'`
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Admin sidebar bleed and keyboard instance resolution (App.vue)</name>
+  <files>frontend/src/App.vue</files>
+  <action>
+    Two root causes, one file. Apply both changes together.
+
+    CHANGE A — Admin sidebar bleed (Gap 3):
+    Insert a v-else-if branch in the template between the auth branch and the user-layout div. The new branch condition is `route.matched.some(r => r.meta.requiresAdmin)`. When true it renders only `<router-view />` — no AppSidebar, no main wrapper. The complete corrected template root (inside the component root, excluding ToastContainer and OsDragOverlay which stay unchanged):
+
+      1. `<AuthLayout v-if="route.meta.layout === 'auth'" />`
+      2. `<router-view v-else-if="route.matched.some(r => r.meta.requiresAdmin)" />`
+      3. `<div v-else class="flex h-screen overflow-hidden">` ... AppSidebar + main + router-view (no ref attribute) ... `</div>`
+
+    Note: the router-view in branch 3 must NOT carry `ref="routeViewRef"` — refs on router-view resolve to the RouterView proxy (same root cause as Gap 4). Remove the ref attribute.
+
+    CHANGE B — Keyboard instance resolution (Gap 4, also fixes tests 12 and 13):
+    The `routeViewRef` ref and its usage must be replaced with a direct instance lookup:
+    1. Add `useRouter` to the `vue-router` import: `import { useRoute, useRouter } from 'vue-router'`
+    2. Add `const router = useRouter()` after `const route = useRoute()`
+    3. Add helper: `function getFileManagerInstance() { return router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default ?? null }`
+    4. Remove `const routeViewRef = ref(null)` — no longer used
+    5. Remove `ref` from the `ref` import if it is now unused (check — ref was only used for routeViewRef)
+    6. Replace all `routeViewRef.value?.X?.()` calls in onKeydown with `getFileManagerInstance()?.X?.()`
+    7. Replace `routeViewRef.value?.handleOsDrop?.(files)` in onOsFilesDropped with `getFileManagerInstance()?.handleOsDrop?.(files)`
+
+    After both changes, `ref` from vue should be removed from the import line if nothing else uses it (check first — if ToastContainer or OsDragOverlay use a local ref, keep it; otherwise remove to avoid lint warnings).
+  </action>
+  <verify>
+    <automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep "routeViewRef" src/App.vue; echo "exit:$?"; grep "instances.default" src/App.vue; grep "requiresAdmin" src/App.vue</automated>
+  </verify>
+  <done>
+    - `grep "routeViewRef" src/App.vue` returns no output (fully removed)
+    - `grep "instances.default" src/App.vue` returns the getFileManagerInstance() line
+    - `grep "requiresAdmin" src/App.vue` returns the v-else-if template branch
+    - `grep "useRouter" src/App.vue` appears in import and instantiation
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Escape modifier (SearchBar.vue) and capture-phase drop (OsDragOverlay.vue)</name>
+  <files>
+    frontend/src/components/documents/SearchBar.vue
+    frontend/src/components/layout/OsDragOverlay.vue
+  </files>
+  <action>
+    SearchBar.vue — one character change on line 11. Add `.prevent.stop` modifiers to `@keydown.escape`:
+    Before: `@keydown.escape="emit('update:modelValue', '')"`
+    After:  `@keydown.escape.prevent.stop="emit('update:modelValue', '')"`
+    `.prevent` stops the browser's native clear+blur behavior on type="search" inputs. `.stop` stops bubbling to App.vue's global keydown handler (which would call clearSearch() a second time). No other changes.
+
+    OsDragOverlay.vue — two lines change in the Options API lifecycle hooks:
+    In mounted(): change `window.addEventListener('drop', this.onDrop)` to `window.addEventListener('drop', this.onDrop, true)`
+    In beforeUnmount(): change `window.removeEventListener('drop', this.onDrop)` to `window.removeEventListener('drop', this.onDrop, true)`
+
+    The third argument `true` registers the listener in capture phase, meaning it runs before any bubble-phase handlers on child elements (including `@drop.prevent` on folder rows in StorageBrowser.vue). The removeEventListener MUST also pass `true` — EventTarget tracks bubble-phase and capture-phase registrations separately, so without `true` the cleanup call would fail silently and the listener would leak.
+
+    Do not change dragenter, dragleave, or dragover listeners — those remain in bubble phase and work correctly.
+  </action>
+  <verify>
+    <automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && grep "keydown.escape" src/components/documents/SearchBar.vue && grep -n "addEventListener.*drop\|removeEventListener.*drop" src/components/layout/OsDragOverlay.vue</automated>
+  </verify>
+  <done>
+    - `grep "keydown.escape" src/components/documents/SearchBar.vue` shows `.prevent.stop` in the modifier chain
+    - `grep "addEventListener.*drop" src/components/layout/OsDragOverlay.vue` shows `true` as third argument
+    - `grep "removeEventListener.*drop" src/components/layout/OsDragOverlay.vue` shows `true` as third argument
+  </done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 4: Regression tests for all 6 gaps</name>
+  <files>
+    frontend/src/__tests__/keyboard.test.js
+    frontend/src/components/ui/__tests__/TreeItem.test.js
+    frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js
+  </files>
+  <behavior>
+    TreeItem shimmer:
+    - When loading=true and expanded=true → rendered HTML contains elements with class "animate-pulse"
+    - When loading=true and expanded=true → text "Loading" does not appear in rendered HTML
+
+    StorageBrowser showSearch:
+    - mode='local', breadcrumb=[] → showSearch is true (root-level local, previously false)
+    - mode='local', breadcrumb=[{name:'Folder'}] → showSearch is true (non-root local)
+    - mode='cloud', breadcrumb=[] → showSearch is true (cloud root, previously always false)
+    - mode='shared' → showSearch is false
+
+    App.vue keyboard dispatch:
+    - matched.find(r => r.instances?.default)?.instances?.default on a mounted FileManagerView router returns an object with focusSearch defined
+  </behavior>
+  <action>
+    keyboard.test.js — append a new describe block at the end of the existing file (do not modify or move existing describes):
+
+    "Gap 4: getFileManagerInstance resolves to actual component, not RouterView proxy" — using the existing mountFileManager() helper and makeRouter(), after mounting FileManagerView and flushing promises, access `router.currentRoute.value.matched.find(r => r.instances?.default)?.instances?.default` and assert that it is not null and has a `focusSearch` property. This proves the resolution mechanism the refactored App.vue uses is correct. Import `useRouter` from vue-router at the top if not already imported — check existing imports first.
+
+    TreeItem.test.js — create at `frontend/src/components/ui/__tests__/TreeItem.test.js`:
+    - Import: `describe, it, expect, vi` from vitest; `mount, flushPromises` from @vue/test-utils; TreeItem from the component
+    - Mock AppIcon: `vi.mock('../AppIcon.vue', () => ({ default: { template: '<span/>' } }))`
+    - Helper: `mountExpanded(overrides = {})` — mounts TreeItem with `label="Test"`, `loadChildren: vi.fn().mockResolvedValue([])`, `expandable: true` and spreads overrides. After mount, call `w.vm.toggleExpand()` via `w.vm.$.setupState.toggleExpand()` (or trigger the expand button click) and flush promises to reach expanded state with children loaded.
+    - For the loading=true test: mount with a loadChildren that returns a promise that never resolves (`new Promise(() => {})`). Click the expand button to trigger load. Before flushing, assert the HTML. The loading ref will be true while the promise is pending.
+    - describe "Gap 1: sidebar shimmer rows": two tests as per behavior block above.
+    - describe "Gap 1 regression: non-loading branches unchanged": one test asserting that with loadChildren resolving to [] and expanded, the "Empty" text appears (sibling v-else-if branch guard).
+
+    StorageBrowser.showSearch.test.js — create at `frontend/src/components/storage/__tests__/StorageBrowser.showSearch.test.js`:
+    - Heavy stub setup: all child components that StorageBrowser imports must be stubbed (SearchBar, SortControls, DocumentCard, FolderRow, EmptyState, AppIcon, BreadcrumbBar, DropZone, etc.) — use `stubs: { SearchBar: true, SortControls: true, ... }` in global mount options or individual vi.mock calls.
+    - Mock all API calls used on mount (listDocuments, listFolders, etc.) via vi.mock('../../../api/client.js', ...).
+    - After mount with given props, access `w.vm.showSearch` directly as a computed.
+    - Props for mount: at minimum `mode`, `breadcrumb`, `documents: []`, `folders: []`, `topicColorFn: () => '#000'`, `loading: false`.
+    - Four it() blocks as per behavior block above.
+    - Wrap in `describe("Gap 2: showSearch visible at root for local and cloud modes", ...)`.
+
+    All new tests run as part of `npm run test -- --run` without additional flags.
+  </action>
+  <verify>
+    <automated>cd /Users/nik/Documents/Progamming/document_scanner/frontend && npm run test -- --reporter=verbose --run 2>&1 | grep -E "(PASS|FAIL|SKIP| ✓ | × | ✗ )" | tail -50</automated>
+  </verify>
+  <done>
+    - All new describe blocks appear in output with passing test indicators
+    - `npm run test -- --run` exits 0 with zero failures
+    - `grep -c "animate-pulse" src/components/ui/__tests__/TreeItem.test.js` returns at least 1
+    - `grep -c "showSearch" src/components/storage/__tests__/StorageBrowser.showSearch.test.js` returns at least 4
+  </done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| OS file drag → window drop (capture) | Files arrive via browser DataTransfer API — browser-enforced; no network boundary crossed; payload handled only client-side before going through existing authenticated upload flow |
+| Admin route layout selection | Template branch selection is display-only — backend enforces admin access via get_current_admin dep on every admin endpoint; changing template rendering creates no auth regression |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-10gc-01 | Tampering | OsDragOverlay capture-phase drop handler | accept | Handler reads only e.dataTransfer.files (browser-controlled), resets overlay state, emits to parent — no direct server interaction; upload goes through existing authenticated API path unchanged |
+| T-10gc-02 | Spoofing | router.currentRoute.value.matched.find().instances.default | accept | Read-only Vue internals lookup; no user-supplied data flows through this path; cannot be spoofed via URL manipulation — Vue populates instances after component mount, not from route params |
+| T-10gc-03 | Elevation of Privilege | App.vue v-else-if admin branch | accept | Branch adds a missing layout guard (removes AppSidebar for admin); it does not grant or deny route access — navigation guard in router/index.js is unchanged and continues to enforce requiresAdmin check |
+| T-10gc-SC | Tampering | npm/pip/cargo installs | accept | No new packages installed — all fixes are template/script edits to existing files |
+</threat_model>
+
+<verification>
+Manual UAT re-run checklist (all must pass before marking complete):
+
+Gap 1 — Sidebar shimmer: Expand a cloud provider tree item in the sidebar while data loads. Animated shimmer rows appear; "Loading…" text is absent.
+
+Gap 2 — Search at root: Navigate to / (file manager root, no folder entered). Search bar and sort controls are visible in the content area header.
+
+Gap 3 — Admin sidebar: Navigate to /admin/users in a logged-in admin session. Only the AdminLayout and AdminSidebar render — AppSidebar (user nav) is absent.
+
+Gap 4 — Keyboard shortcuts: With the file manager at root, press '/'. Search bar receives cursor focus. Press 'U'. File picker dialog opens. Press 'N'. New folder inline input appears.
+
+Gap 5 — Escape behavior: Type text into the search bar. Press Escape. Field clears. Cursor remains in the field. Type again immediately — new characters appear (no re-click required).
+
+Gap 6 — OS drag-drop: Drag a file from Finder/Explorer over the browser window. Overlay appears. Release the file. Upload begins (progress visible or toast appears).
+
+Automated gate:
+`cd frontend && npm run test -- --run` — exits 0, zero failures, no skipped tests regressed.
+</verification>
+
+<success_criteria>
+- All 6 UAT gaps confirmed closed by manual re-run of the 6 scenarios above
+- `npm run test -- --run` exits 0 with zero failures across the full suite (baseline: 211 passing)
+- Five production files modified with surgical changes only — no refactors, no feature additions
+- Three new test files committed with passing tests covering each gap
+- `grep -c "Loading" frontend/src/components/ui/TreeItem.vue` returns 0
+- `grep "showSearch" frontend/src/components/storage/StorageBrowser.vue` matches the `|| props.mode === 'cloud'` form
+- `grep "routeViewRef" frontend/src/App.vue` returns empty
+- `grep "requiresAdmin" frontend/src/App.vue` returns the v-else-if template branch line
+- `grep "addEventListener.*drop.*true" frontend/src/components/layout/OsDragOverlay.vue` returns a match
+- `grep "removeEventListener.*drop.*true" frontend/src/components/layout/OsDragOverlay.vue` returns a match
+- `grep "prevent.stop" frontend/src/components/documents/SearchBar.vue` returns the escape handler line
+</success_criteria>
+
+<output>
+Create `/Users/nik/Documents/Progamming/document_scanner/.planning/phases/10-ux-interaction/10-13-SUMMARY.md` when done.
+</output>

.planning/milestones/v0.2-phases/10-ux-interaction/10-SECURITY.md

@@ -0,0 +1,75 @@
+---
+phase: 10
+slug: ux-interaction
+status: verified
+threats_open: 0
+asvs_level: 2
+created: 2026-06-17
+register_authored_at_plan_time: true
+---
+
+# Phase 10 — Security
+
+> Retroactive security contract for Phase 10: UX & Interaction.
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|---|---|---|
+| Browser window events → Vue UI handlers | Keyboard shortcuts, drag events, modal Escape handlers, and menu positioning are handled client-side only. | Event metadata; no secrets or server-side authority. |
+| OS file drag → `OsDragOverlay` → existing upload flow | Files arrive through the browser `DataTransfer` API and are forwarded into the existing authenticated upload path. | Browser-controlled `File` objects; existing quota/auth checks still apply on upload. |
+| Route metadata → layout selection | `/admin/*` layout selection hides the user sidebar and shows admin chrome. | Route metadata only; backend/admin guard remains unchanged. |
+| Vue templates → user-visible text | Breadcrumbs, empty states, toasts, and dropdown labels render through Vue interpolation. | Store/view strings; Vue escaping preserved. |
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|---|---|---|---|---|---|
+| T-10-01 | Cross-Site Scripting | Breadcrumb, empty state, toast, and dropdown text rendering | mitigate | Vue template interpolation is used; no `v-html` or raw HTML injection introduced by Phase 10 UI components. | closed |
+| T-10-02 | Information Disclosure | Toast notifications | mitigate | Toast payloads are generic action results such as upload/delete/rename/revoke status; no document content, extracted text, credentials, or token material is displayed. | closed |
+| T-10-03 | Tampering | `OsDragOverlay` file drop handling | accept | Handler reads browser-provided `dataTransfer.files`, resets overlay state, and emits to the existing authenticated upload flow; no direct server write bypass is introduced. | closed |
+| T-10-04 | Elevation of Privilege | Admin route layout selection | accept | `App.vue` admin branch changes presentation only; router `requiresAdmin` guard and backend `get_current_admin` enforcement are unchanged. | closed |
+| T-10-05 | Spoofing | Keyboard shortcut dispatch through current route instance | accept | Shortcuts call methods on the mounted Vue route component only; no URL parameter or user-supplied string selects privileged behavior. | closed |
+| T-10-06 | Denial of Service | Global keyboard and drag listeners | mitigate | Event listeners are added once at component mount and removed on unmount; drag overlay uses a bounded `dragDepth` counter and ignores non-file drags. | closed |
+| T-10-07 | Supply Chain | Phase 10 frontend changes | accept | No new runtime packages were introduced by Phase 10; changes are Vue components, tests, and existing Tailwind/Vitest usage. | closed |
+| T-10-08 | Supply Chain | Vite/esbuild dev dependency audit | mitigate | `npm audit --audit-level=high` found GHSA-gv7w-rqvm-qjhr through `vite@6.4.3`/`esbuild@0.25.12`; Vite was upgraded to `^8.0.16`, then audit, tests, and build were re-run. | closed |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---|---|---|---|---|
+| AR-10-01 | T-10-03 | The drop handler cannot bypass upload authorization or quota checks because it delegates to the existing upload flow. | project owner | 2026-06-17 |
+| AR-10-02 | T-10-04 | Layout selection is presentation-only; authorization remains in router/backend gates. | project owner | 2026-06-17 |
+| AR-10-03 | T-10-05 | Route-instance method lookup is local Vue state, not user-controlled input. | project owner | 2026-06-17 |
+| AR-10-04 | T-10-07 | No new dependency was added in Phase 10. | project owner | 2026-06-17 |
+
+## Audit Evidence
+
+| Source | Finding |
+|---|---|
+| `10-01-SUMMARY.md` through `10-12-SUMMARY.md` | Threat flags are either "None" or document UI-only behavior with no new auth/network/schema surface. |
+| `10-13-PLAN.md` | Contains a STRIDE register for the UAT gap-closure plan; all threats have accepted dispositions. |
+| `10-13-SUMMARY.md` | Confirms gap-closure changes are display-only template/event-handler updates with no new network endpoints, auth paths, or schema changes. |
+| `10-VERIFICATION.md` | Confirms 15/15 Phase 10 requirements passed after gap closure and no anti-patterns remain. |
+| `10-VALIDATION.md` | Confirms Phase 10 validation coverage for UX and interaction requirements. |
+| `npm audit --audit-level=high` | Initially found a high-severity esbuild advisory through Vite; after upgrading to Vite `^8.0.16`, npm reported 0 vulnerabilities. |
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|---|---:|---:|---:|---|
+| 2026-06-17 | 8 | 8 | 0 | Codex (milestone audit remediation) |
+
+## Sign-Off
+
+- [x] All threats have a disposition.
+- [x] Accepted risks documented.
+- [x] No Phase 10 change introduces backend routes, auth changes, DB schema changes, or direct storage writes.
+- [x] Existing upload/auth/admin enforcement remains the authority boundary.
+- [x] High-severity npm audit finding resolved by Vite 8 upgrade.
+- [x] `threats_open: 0` confirmed.
+
+**Approval:** verified 2026-06-17

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-01-PLAN.md

@@ -0,0 +1,42 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 1
+type: execute
+wave: 0
+depends_on: [10-complete]
+requirements: [PERF-02]
+files_modified:
+  - frontend/vite.config.js
+  - .planning/phases/11-visual-design-responsive-layout-cleanup/11-RESEARCH.md
+  - .planning/perf/phase11-baseline.html
+  - .planning/perf/phase11-baseline-summary.md
+autonomous: true
+---
+
+# Plan 11-01 — Bundle Baseline & UI Audit
+
+## Objective
+
+Capture the Phase 11 pre-optimization bundle baseline before any lazy-loading or visual cleanup begins, then record a targeted audit of the visual/responsive issues Phase 11 will address.
+
+## Tasks
+
+1. Wire existing `rollup-plugin-visualizer` into `frontend/vite.config.js` behind an opt-in environment flag such as `ANALYZE=true`. The dependency already exists in `frontend/package.json`.
+2. Run a production build with analysis enabled and write the baseline report to `.planning/perf/phase11-baseline.html`.
+3. Add `.planning/perf/phase11-baseline-summary.md` with bundle size, largest chunks, route/component observations, and the exact command used.
+4. Update `11-RESEARCH.md` if execution discovers facts that differ from the refresh research.
+5. Audit the frontend for Phase 11 targets:
+   - synchronous non-critical route imports
+   - responsive sidebar/admin sidebar gaps
+   - tables or grids that overflow below `sm`/`md`
+   - modal overflow below 640px
+   - inconsistent form, hover, focus, active, spacing, and typography patterns
+   - unreferenced files and imports
+
+## Acceptance Criteria
+
+- Baseline bundle report exists before any Phase 11 optimization commits.
+- `vite.config.js` does not generate analyzer output unless explicitly requested.
+- `11-RESEARCH.md` remains accurate after the baseline build.
+- Audit notes are concrete enough that plans 11-02 through 11-06 can execute without rediscovering scope.
+- `cd frontend && npm run build` succeeds with and without analysis enabled.

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-01-SUMMARY.md

@@ -0,0 +1,99 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 1
+subsystem: frontend/build
+tags: [perf, audit, bundle, baseline]
+dependency_graph:
+  requires: [10-complete]
+  provides: [phase11-bundle-baseline, phase11-audit]
+  affects: [frontend/vite.config.js, .planning/perf/]
+tech_stack:
+  added: []
+  patterns: [rollup-plugin-visualizer behind ANALYZE=true env flag]
+key_files:
+  created:
+    - .planning/perf/phase11-baseline.html
+    - .planning/perf/phase11-baseline-summary.md
+  modified:
+    - frontend/vite.config.js
+    - .gitignore
+decisions:
+  - "Async defineConfig factory: visualizer dynamically imported only when ANALYZE=true; zero overhead on normal builds"
+  - "stats.html added to .gitignore; canonical copy stored at .planning/perf/phase11-baseline.html"
+  - "FileManagerView stays synchronous for / per D-10; 5 other user routes are lazy-load candidates for 11-02"
+  - "AccountView.vue is confirmed orphaned (router redirects /account → /settings without rendering it)"
+metrics:
+  duration_minutes: 3
+  tasks_completed: 5
+  files_created: 2
+  files_modified: 2
+  completed_date: "2026-06-16"
+---
+
+# Phase 11 Plan 1: Bundle Baseline & UI Audit Summary
+
+Wired `rollup-plugin-visualizer` behind `ANALYZE=true` opt-in, captured the pre-optimization bundle baseline, and completed a full frontend audit to ground plans 11-02 through 11-06.
+
+## What Was Built
+
+### Task 1 — vite.config.js analyzer wiring
+
+`frontend/vite.config.js` converted from a static `defineConfig` object to an async factory. The visualizer is dynamically imported (`import('rollup-plugin-visualizer')`) only when `ANALYZE=true` is present in the environment, ensuring zero overhead on normal `npm run build` runs. `frontend/stats.html` added to `.gitignore` since it is a build artifact.
+
+### Tasks 2-3 — Bundle baseline
+
+Ran `cd frontend && ANALYZE=true npm run build`. Committed the report to `.planning/perf/phase11-baseline.html` (225 kB interactive treemap). Added `phase11-baseline-summary.md` with chunk sizes, route audit table, and per-plan findings.
+
+**Key numbers:**
+- Main bundle: 264.63 kB raw / 89.34 kB gzip
+- CSS: 98.74 kB raw / 17.12 kB gzip (Tailwind purged)
+- 5 user routes still synchronous in main bundle → lazy-load in 11-02
+
+### Tasks 4-5 — Research validation and frontend audit
+
+Build output confirmed `11-RESEARCH.md` findings exactly — no updates needed. Audit documented in `phase11-baseline-summary.md`:
+
+**Synchronous routes for 11-02:** `TopicsView`, `DocumentView`, `SettingsView`, `CloudStorageView`, `CloudFolderView` (5 routes; `FileManagerView` stays synchronous per D-10).
+
+**Responsive gaps for 11-03:**
+- `App.vue` and `AdminLayout.vue`: desktop-only shell; no hamburger, no drawer, no mobile nav
+- `StorageBrowser.vue`: 5-column `grid-cols` stays fixed even when last 2 columns are hidden below `md`/`sm`; needs responsive `grid-cols` variant
+- Row action buttons `p-1.5` are ~26px — below `md` touch target minimum of 36px
+
+**Modal overflow for 11-04:**
+- `ShareModal.vue`, `CloudCredentialModal.vue`, `FolderDeleteModal.vue`: no `max-h` or `overflow-y-auto`
+- `DocumentPreviewModal.vue`: full-screen — structurally correct; header safe
+
+**Focus/form normalization for 11-04/11-05:**
+- `focus:ring-2` used throughout; needs `focus-visible:` variant instead
+- Inputs carry redundant border/focus class stacks next to `@tailwindcss/forms` defaults
+- Skeleton inline styles in `AppSidebar.vue` can become static Tailwind widths
+
+**Dead code for 11-06:**
+- `AccountView.vue`: confirmed orphan — router redirects `/account → /settings` without importing or rendering it
+- Admin tab test files (`AdminAiConfigTab.test.js`, `AdminQuotasTab.test.js`, `AdminUsersTab.test.js`): classify in 11-06
+
+## Verification
+
+- `npm run build` (no ANALYZE): 152 modules transformed, built in 1.06s — no stats.html generated
+- `ANALYZE=true npm run build`: identical build + `stats.html` written
+- `npm test`: 219 tests pass (30 test files)
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None.
+
+## Threat Flags
+
+None — this plan makes no network, auth, or schema changes.
+
+## Self-Check: PASSED
+
+- `.planning/perf/phase11-baseline.html`: EXISTS (committed at 6d56d25)
+- `.planning/perf/phase11-baseline-summary.md`: EXISTS (committed at 6d56d25)
+- `frontend/vite.config.js`: EXISTS and modified (committed at 0fb2a53)
+- Both commits present in git log: confirmed

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-02-PLAN.md

@@ -0,0 +1,43 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 2
+type: execute
+wave: 1
+depends_on: [11-01]
+requirements: [PERF-03]
+files_modified:
+  - frontend/src/router/index.js
+  - frontend/src/router/__tests__/router.guard.test.js
+autonomous: true
+---
+
+# Plan 11-02 — Lazy-Load Non-Critical Routes
+
+## Objective
+
+Satisfy PERF-03 by lazy-loading every route component that is not needed for the initial render, while preserving auth/admin guard behavior.
+
+## Tasks
+
+1. Keep `FileManagerView` synchronous for `/` as the critical first authenticated surface unless the baseline report shows a strong reason to split it. Document this in `router/index.js` near the import.
+2. Replace synchronous imports in `frontend/src/router/index.js` for non-initial routes:
+   - `TopicsView`
+   - `DocumentView`
+   - `SettingsView`
+   - `CloudStorageView`
+   - `CloudFolderView`
+3. Keep `/folders/:folderId` on the same `FileManagerView` component for behavior parity with `/`; it is already in the initial chunk because `/` uses the same component.
+4. Preserve existing lazy auth/admin/shared route imports.
+5. Extend router tests so guard behavior is verified with lazy route components:
+   - non-admin cannot enter `/admin/*`
+   - admin redirects away from non-admin routes
+   - refresh-before-guard still runs when access token is absent
+   - `/topics`, `/document/:id`, `/settings`, `/cloud`, and `/cloud/:provider/:folderId` still resolve
+6. Build once and confirm route chunks are emitted.
+
+## Acceptance Criteria
+
+- `rg "import .*View" frontend/src/router/index.js` only returns `FileManagerView` unless a new initial-render route is explicitly justified.
+- Admin child routes remain lazy-loaded.
+- Router guard tests pass.
+- `cd frontend && npm run build` succeeds and emits split route chunks.

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-02-SUMMARY.md

@@ -0,0 +1,98 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 2
+subsystem: frontend/router
+tags: [perf, lazy-load, routing, bundle-split, PERF-03]
+dependency_graph:
+  requires: [11-01]
+  provides: [perf03-lazy-routes]
+  affects: [frontend/src/router/index.js, frontend/src/router/__tests__/router.guard.test.js]
+tech_stack:
+  added: []
+  patterns: [dynamic import via () => import() for non-critical route components]
+key_files:
+  created: []
+  modified:
+    - frontend/src/router/index.js
+    - frontend/src/router/__tests__/router.guard.test.js
+decisions:
+  - "FileManagerView stays synchronous for / per D-10 — critical first authenticated surface; lazy-loading would delay initial paint for the most common entry point"
+  - "/folders/:folderId reuses the synchronous FileManagerView so no new chunk is created for folder navigation"
+  - "All other authenticated user routes (Topics, Document, Settings, Cloud, CloudFolder) are now lazy-loaded via () => import()"
+  - "Admin child routes and auth routes were already lazy-loaded and remain unchanged"
+metrics:
+  duration_minutes: 2
+  tasks_completed: 6
+  files_created: 0
+  files_modified: 2
+  completed_date: "2026-06-16"
+---
+
+# Phase 11 Plan 2: Lazy-Load Non-Critical Routes Summary
+
+Lazy-loaded 5 non-critical authenticated route components, reducing the main JS bundle from 264.63 kB to 180.17 kB and emitting 5 separate route chunks, satisfying PERF-03.
+
+## What Was Built
+
+### Tasks 1-4 — Router lazy-loading
+
+`frontend/src/router/index.js` updated:
+
+- **Removed** static `import` statements for `TopicsView`, `DocumentView`, `SettingsView`, `CloudStorageView`, `CloudFolderView`.
+- **Replaced** each with an inline `() => import('../views/...View.vue')` dynamic import on the route's `component` field.
+- **Kept** `FileManagerView` as the sole static synchronous import (decision D-10). A comment block in `router/index.js` documents the rationale.
+- **Kept** `/folders/:folderId` using the synchronous `FileManagerView` component — no new chunk needed since the component is already in the initial bundle.
+- **Preserved** all existing lazy imports for admin children, auth views, `SharedView`, and `AdminLayout`.
+
+Acceptance criterion confirmed: `grep "import .*View" frontend/src/router/index.js` returns only `FileManagerView`.
+
+### Task 5 — Extended router guard tests
+
+`frontend/src/router/__tests__/router.guard.test.js` extended with 15 new tests across 2 new describe blocks:
+
+- `router — admin guard` extended with: non-admin blocked from `/admin/users` and `/admin/quotas` (child route inheritance via `to.matched.some()`), admin redirected away from `/settings` and `/cloud` (D-09)
+- `router — refresh-before-guard` (new): verifies `refresh()` is called when `accessToken` is null, redirect to `/login` when refresh fails, no refresh call for public routes
+- `router — lazy-loaded routes resolve` (new): verifies all 5 newly-lazy routes (`/topics`, `/topics/:name`, `/document/:id`, `/settings`, `/cloud`, `/cloud/:provider/:folderId`) navigate correctly for authenticated regular users; `/folders/:folderId` and `/shared` also covered
+
+All 234 tests pass (up from 219 in Plan 11-01).
+
+### Task 6 — Build verification
+
+`npm run build` succeeds; route chunks emitted:
+
+| Chunk | Size |
+|-------|------|
+| `CloudFolderView-*.js` | 1.99 kB |
+| `CloudStorageView-*.js` | 2.32 kB |
+| `DocumentView-*.js` | 9.17 kB |
+| `TopicsView-*.js` | 10.98 kB |
+| `SettingsView-*.js` | 60.72 kB |
+| Main bundle (`index-*.js`) | 180.17 kB (was 264.63 kB) |
+
+Main bundle reduction: **84.46 kB raw** (~32%).
+
+## Verification
+
+- `rg "import .*View" frontend/src/router/index.js` returns only `FileManagerView` — confirmed
+- Admin child routes remain lazy-loaded — confirmed
+- `npm test`: 234 tests pass, 30 test files
+- `npm run build`: succeeds, split route chunks emitted
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None.
+
+## Threat Flags
+
+None — this plan makes no network, auth, or schema changes. Guard behavior is unchanged; only the loading strategy for view components was modified.
+
+## Self-Check: PASSED
+
+- `frontend/src/router/index.js`: modified, only `FileManagerView` statically imported
+- `frontend/src/router/__tests__/router.guard.test.js`: modified, 15 new tests
+- Commit `4fa07b3` exists in git log
+- Build output shows 5 route chunk files

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-03-PLAN.md

@@ -0,0 +1,52 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 3
+type: execute
+wave: 2
+depends_on: [11-02]
+requirements: [RESP-01, RESP-02, RESP-03, RESP-05]
+files_modified:
+  - frontend/src/App.vue
+  - frontend/src/layouts/AdminLayout.vue
+  - frontend/src/components/layout/AppSidebar.vue
+  - frontend/src/components/admin/AdminSidebar.vue
+  - frontend/src/components/storage/StorageBrowser.vue
+  - frontend/src/__tests__/keyboard.test.js
+  - frontend/src/components/storage/__tests__/StorageBrowser.skeleton.test.js
+autonomous: true
+---
+
+# Plan 11-03 — Responsive Shells & Storage Rows
+
+## Objective
+
+Make both user and admin layouts usable below `lg`, and make storage rows fit smaller viewports without losing core actions.
+
+## Tasks
+
+1. Use layout-local drawer refs, not a new Pinia store:
+   - `App.vue` owns user drawer state.
+   - `AdminLayout.vue` owns admin drawer state.
+   - Watch route changes in each layout root and close the drawer after navigation.
+   - Do not put drawer state in `AppSidebar.vue` or `AdminSidebar.vue`.
+2. Add a mobile-only header with a hamburger button for the user layout.
+3. Hide `AppSidebar` below `lg`; open it in a slide-in overlay drawer with backdrop tap, route-change close, and `translate-x-0` / `-translate-x-full` transition.
+4. Apply the same responsive shell behavior to `AdminLayout` and `AdminSidebar`.
+5. Update `StorageBrowser` row/grid classes so:
+   - Size column hides below `md`
+   - Modified column hides below `sm`
+   - icon, name, and actions remain visible
+   - grid templates do not reserve hidden column widths on mobile
+6. Ensure inline icon action buttons have at least `36px` touch targets below `md`.
+7. Add or update tests for drawer open/close, route-change close, admin drawer behavior, responsive column classes, and touch target classes.
+8. Verify with browser screenshots or Playwright at 375px, 768px, 1024px, and desktop width.
+
+## Acceptance Criteria
+
+- User sidebar is hidden below 1024px and accessible through a hamburger drawer.
+- Admin sidebar has matching mobile behavior.
+- Drawer closes on backdrop tap and navigation tap.
+- Storage rows satisfy RESP-02 without horizontal overflow at 375px.
+- Icon actions satisfy RESP-03.
+- Drawer state is owned only by `App.vue` and `AdminLayout.vue`.
+- Frontend tests and build pass.

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-03-SUMMARY.md

@@ -0,0 +1,131 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 3
+subsystem: frontend/responsive
+tags: [responsive, layout, drawer, touch-targets, RESP-01, RESP-02, RESP-03, RESP-05]
+dependency_graph:
+  requires: [11-02]
+  provides: [responsive-user-shell, responsive-admin-shell, responsive-storage-rows, touch-targets]
+  affects:
+    - frontend/src/App.vue
+    - frontend/src/layouts/AdminLayout.vue
+    - frontend/src/components/storage/StorageBrowser.vue
+tech_stack:
+  added: []
+  patterns:
+    - "Hamburger button + slide-in overlay drawer with Teleport backdrop (translate-x-0/-translate-x-full)"
+    - "Drawer state owned by layout root (App.vue / AdminLayout.vue), not sidebar component (D-04/D-05)"
+    - "Route-change watcher closes drawer automatically on navigation"
+    - "Responsive grid-cols variants: mobile base, sm (+modified), md (all 5 columns)"
+    - "Touch target floor: min-w-[36px] min-h-[36px] on action buttons"
+key_files:
+  created: []
+  modified:
+    - frontend/src/App.vue
+    - frontend/src/layouts/AdminLayout.vue
+    - frontend/src/components/storage/StorageBrowser.vue
+    - frontend/src/__tests__/keyboard.test.js
+    - frontend/src/components/storage/__tests__/StorageBrowser.skeleton.test.js
+decisions:
+  - "Drawer state in App.vue ref (not Pinia, not AppSidebar) — satisfies D-04/D-05 pitfall constraint"
+  - "Backdrop teleported to <body> via <Teleport to='body'> — consistent with Phase 10 modal/toast pattern"
+  - "Grid templates use mobile-first responsive variants instead of a fixed 5-column layout — prevents horizontal overflow at 375px"
+  - "Touch targets applied via min-w/min-h classes at all breakpoints, removed with md:min-w-0 md:min-h-0 at desktop — desktop appearance unchanged"
+metrics:
+  duration_minutes: 9
+  tasks_completed: 8
+  files_created: 0
+  files_modified: 5
+  completed_date: "2026-06-16"
+---
+
+# Phase 11 Plan 3: Responsive Shells & Storage Rows Summary
+
+Implemented mobile-first responsive shells for both user and admin layouts using hamburger-triggered slide-in overlay drawers, and made StorageBrowser rows fit small viewports without horizontal overflow.
+
+## What Was Built
+
+### Tasks 1-3 — App.vue: user layout responsive shell (RESP-01)
+
+`frontend/src/App.vue` updated:
+
+- **Drawer state:** `drawerOpen = ref(false)` owned by `App.vue` — satisfies D-04/D-05 constraint (never put in `AppSidebar`).
+- **Route-change close:** `watch(() => route.fullPath, ...)` sets `drawerOpen.value = false` on every navigation so link taps auto-close the drawer.
+- **Mobile header:** `<header class="lg:hidden fixed ...">` contains the hamburger button (`data-test="hamburger-btn"`) and the DocuVault wordmark. Only shown below `lg`.
+- **Backdrop:** `<Teleport to="body">` wraps a semi-transparent overlay `<div>` that appears when `drawerOpen` is true and calls `drawerOpen = false` on click. Uses `data-test="drawer-backdrop"`.
+- **Sidebar wrapper:** `fixed inset-y-0 left-0 z-50` positioning for mobile, `lg:static lg:z-auto lg:translate-x-0` for desktop. Transition: `translate-x-0` (open) / `-translate-x-full` (closed) via `transition-transform duration-200`. Attribute `data-test="app-sidebar-wrapper"`.
+- **Main content:** `pt-[53px] lg:pt-0` offset on `<main>` so mobile content doesn't hide under the fixed header.
+
+### Task 4 — AdminLayout.vue: admin layout responsive shell (RESP-05)
+
+`frontend/src/layouts/AdminLayout.vue` mirrors the user layout pattern exactly:
+
+- `drawerOpen = ref(false)` + `watch(() => route.fullPath, ...)` for auto-close on navigation.
+- Mobile header shows "DocuVault" + "Admin" label with `data-test="admin-hamburger-btn"`.
+- Teleport backdrop with `data-test="admin-drawer-backdrop"`.
+- Sidebar wrapper with `data-test="admin-sidebar-wrapper"` and identical transition classes.
+- `useRoute` import added; no `useRouter` needed (AdminLayout itself doesn't navigate).
+
+### Tasks 5-6 — StorageBrowser.vue: responsive grid and touch targets (RESP-02, RESP-03)
+
+`frontend/src/components/storage/StorageBrowser.vue` updated:
+
+**Responsive grid templates** (replaces fixed `grid-cols-[2rem_1fr_6rem_8rem_6rem]` everywhere):
+
+| Breakpoint | Grid template | Visible columns |
+|---|---|---|
+| Default (< sm, 375px) | `grid-cols-[2rem_1fr_6rem]` | icon, name, actions |
+| sm (640px+) | `sm:grid-cols-[2rem_1fr_8rem_6rem]` | + modified date |
+| md (768px+) | `md:grid-cols-[2rem_1fr_6rem_8rem_6rem]` | + size |
+
+Applied to: list header row, new-folder input row, folder rows, file rows, skeleton rows.
+
+Added `data-test="list-header"` to the column header row for testability.
+
+**Touch targets** (RESP-03, satisfies 36px minimum):
+
+All inline action buttons (Rename, Delete for folders; Share, Move, Delete for files) now have:
+- `min-w-[36px] min-h-[36px]` — enforces 36×36px minimum hit area on mobile
+- `md:min-w-0 md:min-h-0` — removes the override at desktop so padding-only sizing applies
+- `flex items-center justify-center` — keeps icon centered within the larger target
+
+### Task 7 — Tests
+
+**`frontend/src/components/storage/__tests__/StorageBrowser.skeleton.test.js`** updated:
+
+- Replaced old `grid-cols-[2rem_1fr_6rem_8rem_6rem]` assertion (now broken by responsive refactor) with two tests: mobile base class `grid-cols-[2rem_1fr_6rem]` and md breakpoint class `md:grid-cols-[2rem_1fr_6rem_8rem_6rem]`.
+- Added new `RESP-02/RESP-03` describe block (8 tests): list header mobile/md classes, folder row, file row, `hidden md:block` size column, `hidden sm:block` modified column, file action button `min-w-[36px]`/`min-h-[36px]`, folder action button touch targets.
+
+**`frontend/src/__tests__/keyboard.test.js`** extended:
+
+- Added `RESP-01: App drawer` describe (2 tests): hamburger open/backdrop-close behavior via stub component; route-change watcher closes drawer.
+- Added `RESP-05: AdminLayout drawer` describe (3 tests): admin hamburger renders, admin backdrop-close, admin route-change watcher.
+- `afterEach` import added; `nextTick` import added.
+
+## Verification
+
+- `npm test`: 30 test files, 233 tests pass (219 baseline + 14 new from this plan)
+- `npm run build`: succeeds — 5 JS chunks + main bundle, no new errors
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None.
+
+## Threat Flags
+
+None — no network endpoints, auth paths, or schema changes in this plan. All changes are frontend layout/presentation only.
+
+## Self-Check: PASSED
+
+- `frontend/src/App.vue`: modified — hamburger header + drawer + Teleport backdrop
+- `frontend/src/layouts/AdminLayout.vue`: modified — admin responsive shell
+- `frontend/src/components/storage/StorageBrowser.vue`: modified — responsive grid + touch targets
+- `frontend/src/__tests__/keyboard.test.js`: modified — drawer tests added
+- `frontend/src/components/storage/__tests__/StorageBrowser.skeleton.test.js`: modified — responsive assertions
+- Commit `d914761` exists in git log: confirmed
+- All 30 test files pass: confirmed
+- Build succeeds: confirmed

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-04-PLAN.md

@@ -0,0 +1,40 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 4
+type: execute
+wave: 3
+depends_on: [11-03]
+requirements: [VISUAL-02, RESP-04]
+files_modified:
+  - frontend/tailwind.config.js
+  - frontend/src/components/**/*.vue
+  - frontend/src/views/**/*.vue
+autonomous: true
+---
+
+# Plan 11-04 — Forms Baseline & Mobile-Safe Modals
+
+## Objective
+
+Normalize form controls through `@tailwindcss/forms` and make every modal scroll safely on mobile viewports.
+
+## Tasks
+
+1. Confirm `@tailwindcss/forms` remains installed and active in `tailwind.config.js`; it is already wired today, so this should be a verification step unless execution finds drift.
+2. Audit inputs, selects, textareas, checkboxes, and radio buttons for conflicting per-component browser-reset styles.
+3. Normalize form classes to the smallest consistent Tailwind pattern already used by the app.
+4. Update modal shells so content below 640px is scrollable and never exceeds viewport height:
+   - `ShareModal.vue`: centered panel gets mobile `max-h` and `overflow-y-auto`.
+   - `CloudCredentialModal.vue`: tall WebDAV/Nextcloud form gets mobile `max-h` and `overflow-y-auto`.
+   - `FolderDeleteModal.vue`: adopt the same mobile-safe panel pattern.
+   - `DocumentPreviewModal.vue`: preserve full-screen preview but verify header/content sizing at narrow widths.
+   - any auth/account confirmation modal-like surfaces found in the audit
+5. Add focused tests or DOM assertions for mobile-safe modal classes and form baseline coverage.
+
+## Acceptance Criteria
+
+- Forms plugin is active and relied on consistently.
+- No modal content overflows a 375x667 viewport.
+- No modal text or action row is clipped below 640px.
+- The desktop modal appearance remains behaviorally unchanged.
+- `npm run test -- --run` and `npm run build` pass.

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-04-SUMMARY.md

@@ -0,0 +1,148 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 4
+subsystem: frontend/modals
+tags: [mobile, modals, forms, VISUAL-02, RESP-04]
+dependency_graph:
+  requires: [11-03]
+  provides: [mobile-safe-modals, form-baseline-coverage]
+  affects:
+    - frontend/src/components/sharing/ShareModal.vue
+    - frontend/src/components/cloud/CloudCredentialModal.vue
+    - frontend/src/components/folders/FolderDeleteModal.vue
+    - frontend/src/components/documents/DocumentPreviewModal.vue
+    - frontend/src/views/DocumentView.vue
+tech_stack:
+  added: []
+  patterns:
+    - "max-h-[90vh] overflow-y-auto on modal panels — scroll-safe mobile pattern"
+    - "px-4 sm:px-6 responsive horizontal padding on full-screen preview header"
+    - "data-test attributes on all modal panels for testability"
+    - "focus:outline-none focus:ring-2 focus:ring-indigo-500 — consistent form baseline pattern throughout codebase"
+key_files:
+  created:
+    - frontend/src/components/sharing/__tests__/ShareModal.mobile.test.js
+    - frontend/src/components/cloud/__tests__/CloudCredentialModal.mobile.test.js
+    - frontend/src/components/folders/__tests__/FolderDeleteModal.mobile.test.js
+    - frontend/src/components/documents/__tests__/DocumentPreviewModal.mobile.test.js
+  modified:
+    - frontend/src/components/sharing/ShareModal.vue
+    - frontend/src/components/cloud/CloudCredentialModal.vue
+    - frontend/src/components/folders/FolderDeleteModal.vue
+    - frontend/src/components/documents/DocumentPreviewModal.vue
+    - frontend/src/views/DocumentView.vue
+decisions:
+  - "@tailwindcss/forms plugin active in tailwind.config.js — no drift found, verification task complete"
+  - "focus:outline-none focus:ring-2 focus:ring-indigo-500 is the consistent form baseline pattern throughout entire codebase — no normalization needed"
+  - "DocumentPreviewModal stays full-screen (fixed inset-0) — added responsive px-4 sm:px-6 header padding for narrow viewports"
+  - "DocumentView inline cloud-delete warning modal receives same max-h treatment as dedicated modal components"
+metrics:
+  duration_minutes: 7
+  tasks_completed: 5
+  files_created: 4
+  files_modified: 5
+  completed_date: "2026-06-16"
+---
+
+# Phase 11 Plan 4: Forms Baseline & Mobile-Safe Modals Summary
+
+Verified `@tailwindcss/forms` remains active with a consistent form focus pattern throughout the codebase, and updated all four modal components plus one inline modal to scroll safely on narrow mobile viewports (375x667px).
+
+## What Was Built
+
+### Task 1 — Forms plugin verification
+
+`frontend/tailwind.config.js` confirmed: `import forms from '@tailwindcss/forms'` and `plugins: [forms]` are active. No drift.
+
+### Tasks 2-3 — Form baseline audit and normalization
+
+Full audit of all `<input>`, `<select>`, `<textarea>`, `<input type="checkbox">`, and `<input type="radio">` elements across all Vue components. Findings:
+
+- **Consistent pattern throughout:** `focus:outline-none focus:ring-2 focus:ring-indigo-500` (or `focus:ring-indigo-400` in topic-related components). This is already the standardized baseline.
+- **No conflicting per-component reset styles** found (no `appearance-none`, no `webkit-appearance`, no inline `outline: none`).
+- **No normalization required** — the codebase is already consistent. The forms plugin resets browser defaults and the `focus:ring-*` utility classes provide the visual indicator.
+
+### Task 4 — Modal mobile-safe updates (RESP-04)
+
+All modal panels now have `max-h-[90vh] overflow-y-auto` added to their panel containers:
+
+**`ShareModal.vue`**
+- Panel `class` updated: added `max-h-[90vh] overflow-y-auto`
+- Added `data-test="share-modal-panel"` for testability
+
+**`CloudCredentialModal.vue`**
+- Panel `class` updated: added `max-h-[90vh] overflow-y-auto`
+- Added `data-test="cloud-credential-modal-panel"` for testability
+- The tall WebDAV/Nextcloud form with server URL, username, auth method toggle, advanced section, and password field now scrolls safely on 375px height-constrained viewports
+
+**`FolderDeleteModal.vue`**
+- Panel `class` updated: added `max-h-[90vh] overflow-y-auto`
+- Added `data-test="folder-delete-modal-panel"` for testability
+
+**`DocumentPreviewModal.vue`**
+- Full-screen overlay preserved (`fixed inset-0 flex flex-col`) — this modal intentionally uses the entire viewport
+- Header padding made responsive: `px-4 sm:px-6` (was `px-6`) — prevents filename and close button from touching screen edges at 375px
+- Added `data-test="document-preview-modal"` on overlay and `data-test="preview-modal-header"` on header bar
+
+**`DocumentView.vue` (inline cloud-delete warning modal)**
+- Inline modal panel updated: added `max-h-[90vh] overflow-y-auto`
+- Added `data-test="cloud-delete-modal-panel"` for testability
+
+### Task 5 — Tests
+
+Four new test files created (34 total test files in worktree, 234 tests all pass):
+
+**`ShareModal.mobile.test.js`** (5 tests):
+- VISUAL-02: text input has `focus:ring-2 focus:outline-none` (form baseline)
+- VISUAL-02: select has `focus:ring-2 focus:outline-none` (form baseline)
+- RESP-04: panel has `max-h-[90vh]`
+- RESP-04: panel has `overflow-y-auto`
+- RESP-04: panel has `mx-4` for narrow viewport fit
+
+**`CloudCredentialModal.mobile.test.js`** (3 tests):
+- RESP-04: panel has `max-h-[90vh]`
+- RESP-04: panel has `overflow-y-auto`
+- RESP-04: panel not rendered when `show=false` (v-if gate verified)
+
+**`FolderDeleteModal.mobile.test.js`** (4 tests):
+- RESP-04: panel has `max-h-[90vh]`
+- RESP-04: panel has `overflow-y-auto`
+- RESP-04: panel has `mx-4`
+- Action buttons are accessible (text content check)
+
+**`DocumentPreviewModal.mobile.test.js`** (3 tests):
+- RESP-04: full-screen overlay has `fixed inset-0` classes
+- RESP-04: header has `px-4` (mobile) and `sm:px-6` (640px+)
+- RESP-04: filename `span` has `truncate` class preventing overflow
+
+## Verification
+
+- `npm run test -- --run` (via `./node_modules/.bin/vitest run`): **34 test files, 234 tests, all pass**
+- `npm run build` (via `./node_modules/.bin/vite build`): **succeeds** — all 5 JS chunks + main bundle build cleanly
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None.
+
+## Threat Flags
+
+None — no network endpoints, auth paths, file access patterns, or schema changes. All changes are frontend layout/presentation classes and test files.
+
+## Self-Check: PASSED
+
+- `frontend/src/components/sharing/ShareModal.vue`: modified — max-h + overflow-y-auto + data-test
+- `frontend/src/components/cloud/CloudCredentialModal.vue`: modified — max-h + overflow-y-auto + data-test
+- `frontend/src/components/folders/FolderDeleteModal.vue`: modified — max-h + overflow-y-auto + data-test
+- `frontend/src/components/documents/DocumentPreviewModal.vue`: modified — responsive px-4, data-test attrs
+- `frontend/src/views/DocumentView.vue`: modified — inline modal max-h + data-test
+- `frontend/src/components/sharing/__tests__/ShareModal.mobile.test.js`: created — 5 tests
+- `frontend/src/components/cloud/__tests__/CloudCredentialModal.mobile.test.js`: created — 3 tests
+- `frontend/src/components/folders/__tests__/FolderDeleteModal.mobile.test.js`: created — 4 tests
+- `frontend/src/components/documents/__tests__/DocumentPreviewModal.mobile.test.js`: created — 3 tests
+- Commit `df53cef` exists in git log: confirmed
+- 34 test files, 234 tests all pass: confirmed
+- Build succeeds: confirmed

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-05-PLAN.md

@@ -0,0 +1,46 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 5
+type: execute
+wave: 4
+depends_on: [11-04]
+requirements: [VISUAL-01, VISUAL-03, VISUAL-04]
+files_modified:
+  - frontend/src/components/**/*.vue
+  - frontend/src/views/**/*.vue
+autonomous: true
+---
+
+# Plan 11-05 — Visual Consistency Pass
+
+## Objective
+
+Make spacing, typography, hover, focus-visible, and active states consistent across the frontend without introducing a component-library rewrite.
+
+## Tasks
+
+1. Preserve legitimate data-driven inline styles:
+   - topic color swatches
+   - quota/progress widths
+   - Teleport dropdown coordinates
+   - tree indentation
+2. Remove arbitrary spacing and decorative inline styles unless they are data-driven layout values with no Tailwind equivalent.
+3. Normalize typography to this app scale:
+   - page title: `text-2xl font-semibold`
+   - section title: `text-lg font-semibold`
+   - panel/table heading: `text-sm font-semibold`
+   - body: `text-sm`
+   - caption/metadata: `text-xs`
+4. Replace generic `focus:ring-*` only patterns on interactive elements with this keyboard focus convention: `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-1`.
+5. Ensure buttons, links, card rows, table rows, menu items, and icon actions have coherent hover and active states.
+6. Avoid broad palette changes; preserve the current DocuVault identity while removing one-off visual drift.
+7. Add focused tests or static checks for the agreed invariants where practical.
+
+## Acceptance Criteria
+
+- No unnecessary `px-[...]`, margin `style=`, or one-off typography overrides remain.
+- Interactive elements have hover plus keyboard-visible focus states.
+- Typography reads as one app scale, not per-component choices.
+- Data-driven inline styles remain where they carry runtime values.
+- Visual changes are behavior-preserving.
+- Frontend tests and build pass.

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-05-SUMMARY.md

@@ -0,0 +1,204 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 5
+subsystem: frontend/visual-consistency
+tags: [visual, typography, focus-visible, hover, active, skeleton, VISUAL-01, VISUAL-03, VISUAL-04]
+dependency_graph:
+  requires: [11-04]
+  provides: [typography-normalized, focus-visible-rings, active-states, skeleton-class-widths]
+  affects:
+    - frontend/src/components/admin/AdminSidebar.vue
+    - frontend/src/components/auth/BackupCodesDisplay.vue
+    - frontend/src/components/cloud/CloudCredentialModal.vue
+    - frontend/src/components/documents/DocumentCard.vue
+    - frontend/src/components/layout/AppSidebar.vue
+    - frontend/src/components/settings/SettingsAccountTab.vue
+    - frontend/src/components/settings/SettingsAiTab.vue
+    - frontend/src/components/settings/SettingsCloudTab.vue
+    - frontend/src/components/settings/SettingsPreferencesTab.vue
+    - frontend/src/components/storage/StorageBrowser.vue
+    - frontend/src/components/topics/TopicManager.vue
+    - frontend/src/views/DocumentView.vue
+    - frontend/src/views/SettingsView.vue
+    - frontend/src/views/SharedView.vue
+    - frontend/src/views/TopicsView.vue
+    - frontend/src/views/admin/AdminAiView.vue
+    - frontend/src/views/admin/AdminAuditView.vue
+    - frontend/src/views/admin/AdminOverviewView.vue
+    - frontend/src/views/admin/AdminUsersView.vue
+tech_stack:
+  added: []
+  patterns:
+    - "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-1 — keyboard focus convention for all interactive elements"
+    - "active:bg-{color}-{shade} — press feedback on all primary and secondary buttons"
+    - "w-12/w-16/w-20 Tailwind classes instead of inline :style={{ width }} for skeleton placeholders"
+    - "Typography scale: text-2xl font-semibold (page title), text-lg font-semibold (section title), text-sm font-semibold (panel heading)"
+key_files:
+  created:
+    - frontend/src/components/layout/__tests__/AppSidebar.visual.test.js
+    - frontend/src/views/__tests__/typography.visual.test.js
+  modified:
+    - frontend/src/components/admin/AdminSidebar.vue
+    - frontend/src/components/auth/BackupCodesDisplay.vue
+    - frontend/src/components/cloud/CloudCredentialModal.vue
+    - frontend/src/components/documents/DocumentCard.vue
+    - frontend/src/components/layout/AppSidebar.vue
+    - frontend/src/components/settings/SettingsAccountTab.vue
+    - frontend/src/components/settings/SettingsAiTab.vue
+    - frontend/src/components/settings/SettingsCloudTab.vue
+    - frontend/src/components/settings/SettingsPreferencesTab.vue
+    - frontend/src/components/storage/StorageBrowser.vue
+    - frontend/src/components/topics/TopicManager.vue
+    - frontend/src/views/DocumentView.vue
+    - frontend/src/views/SettingsView.vue
+    - frontend/src/views/SharedView.vue
+    - frontend/src/views/TopicsView.vue
+    - frontend/src/views/admin/AdminAiView.vue
+    - frontend/src/views/admin/AdminAuditView.vue
+    - frontend/src/views/admin/AdminOverviewView.vue
+    - frontend/src/views/admin/AdminUsersView.vue
+decisions:
+  - "Typography scale locked: text-2xl font-semibold for page titles, text-lg font-semibold for section card headings, text-sm font-semibold for panel/table headings"
+  - "focus-visible: convention chosen over focus: on interactive buttons to avoid ring on mouse click — form inputs keep existing focus: pattern (appropriate for forms)"
+  - "Stat number displays (AdminOverview cards, TopicsView doc count) keep font-bold — these are metric numerals, not headings"
+  - "AuthLayout DocuVault brand name keeps text-xl font-semibold — branding element, not a page title"
+  - "Sidebar nav-link scoped CSS updated in both AppSidebar and AdminSidebar to include active:bg-gray-200 and focus-visible ring as @apply directives"
+metrics:
+  duration_minutes: 10
+  tasks_completed: 7
+  files_created: 2
+  files_modified: 19
+  completed_date: "2026-06-16"
+---
+
+# Phase 11 Plan 5: Visual Consistency Pass Summary
+
+Normalized typography to one consistent scale across all views and components, replaced generic `focus:ring-*` patterns with keyboard-only `focus-visible:` convention on all interactive buttons, added `active:bg-*` press feedback states, and converted decorative skeleton inline styles to static Tailwind width classes.
+
+## What Was Built
+
+### Task 1 — Preserve data-driven inline styles
+
+Audited and confirmed the following inline styles are data-driven and preserved:
+- `{ backgroundColor: topic.color }` — topic color swatches in TopicBadge, AppSidebar, TopicsView
+- `{ width: pct + '%' }` — QuotaBar progress fill (runtime percentage)
+- `pickerStyle` (top/left/bottom/width computed from getBoundingClientRect) — Teleport dropdown coordinates in StorageBrowser and DocumentCard
+- Tree indentation via depth-computed padding in FolderTreeItem via TreeItem
+
+### Task 2 — Remove decorative inline styles
+
+Three sections in `AppSidebar.vue` used `:style="{ width: (50 + n * 15) + 'px' }"` for skeleton placeholder widths. Replaced all 9 instances (3 sections × 3 skeleton rows) with static Tailwind classes `w-12`, `w-16`, `w-20` (equivalent visual widths without runtime computation).
+
+### Task 3 — Normalize typography
+
+**Page titles (`text-2xl font-semibold`):**
+- `TopicsView.vue`: `font-bold` → `font-semibold`
+- `DocumentView.vue`: `font-bold` → `font-semibold`
+- `SharedView.vue`: `font-bold` → `font-semibold`
+- `AdminOverviewView.vue`: `text-xl` → `text-2xl font-semibold`
+
+**Section titles (`text-lg font-semibold`):**
+- `SettingsPreferencesTab.vue`: `text-xl` → `text-lg`
+- `SettingsAiTab.vue`: `text-xl` → `text-lg`
+- `SettingsCloudTab.vue`: `text-xl` → `text-lg`
+- `BackupCodesDisplay.vue`: `text-xl` → `text-lg`
+- `CloudCredentialModal.vue`: `text-xl` → `text-lg`
+
+**Panel headings (`text-sm font-semibold`):**
+- `SettingsAccountTab.vue`: 4 h3 headings — added `text-sm` (was `font-semibold` without explicit size)
+- `DocumentView.vue`: 2 h3 headings (Topics, Extracted Text) — added `text-sm`
+
+### Task 4 — Replace focus:ring patterns with focus-visible convention
+
+Applied `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-1` to:
+- All sidebar nav links (via scoped CSS `.nav-link` `@apply` in AppSidebar + AdminSidebar)
+- Expand/collapse toggle buttons in AppSidebar
+- Sign-out button in AppSidebar and AdminSidebar
+- StorageBrowser: New Folder button, rename/delete/share/move/delete icon action buttons
+- DocumentView: Back button, Preview/Delete/Re-classify/Suggest/cloud-modal buttons
+- TopicsView: All Topics back button, topic card router-links
+- SettingsView: tab strip buttons, dismiss buttons
+- TopicManager: Add/Save/Cancel/Edit/Delete buttons
+- DocumentCard: Move and Share icon action buttons
+- AdminAuditView: Apply/Clear/Export/Previous/Next/Download buttons
+- AdminUsersView: Create User button (header and form submit)
+- AdminAiView: all accordion and action buttons
+- SettingsCloudTab: all Connect/Edit/Remove/Disconnect buttons
+- SettingsAccountTab: Disable 2FA and Sign out all buttons
+- BackupCodesDisplay: Copy all + Enable 2FA buttons
+- CloudCredentialModal: Close button
+
+Destructive actions use `focus-visible:ring-red-500` instead of indigo.
+
+### Task 5 — Coherent hover and active states
+
+Added `active:bg-{color}-{shade}` to all interactive elements that lacked press feedback:
+- Primary buttons: `active:bg-indigo-800`
+- Secondary/border buttons: `active:bg-gray-100`
+- Icon action buttons: `active:bg-gray-300` (neutral), `active:bg-red-100` (destructive)
+- Nav links: `active:bg-gray-200` via scoped CSS
+- Folder picker dropdown items: `active:bg-gray-100` / `active:bg-indigo-100`
+- Green "Set Active" button in AdminAiView: `active:bg-green-800`
+
+### Task 6 — Palette preservation
+
+No new colors introduced. Existing DocuVault identity preserved:
+- amber/folders, sky/cloud, indigo/admin/primary, red/destructive, green/success
+- Focus rings use indigo-500 for primary elements, red-500 for destructive elements, green-500 for success buttons
+
+### Task 7 — Tests
+
+**`AppSidebar.visual.test.js`** (4 tests):
+- VISUAL-01: cloud skeleton items use `w-*` class not inline style width
+- VISUAL-01: topics skeleton items use class-based widths not inline style
+- VISUAL-04: expand/collapse folder toggle button has `focus-visible:ring-2` and `focus-visible:ring-indigo-500`
+- VISUAL-04: sign-out button has `focus-visible:ring-2`
+
+**`typography.visual.test.js`** (3 tests):
+- VISUAL-03: SharedView h2 has `font-semibold` not `font-bold` and `text-2xl`
+- VISUAL-03: TopicsView h2 has `font-semibold` not `font-bold` and `text-2xl`
+- VISUAL-03: SettingsAccountTab h3 headings don't use `text-xl` or `font-bold`
+
+## Verification
+
+- `./node_modules/.bin/vitest run`: **36 test files, 270 tests, all pass**
+- `./node_modules/.bin/vite build`: **succeeds** — all chunks build cleanly
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None — all data displayed is wired to real store/API data. No placeholder text or hardcoded values introduced.
+
+## Threat Flags
+
+None — all changes are frontend presentation classes and test files. No network endpoints, auth paths, file access patterns, or schema changes.
+
+## Self-Check: PASSED
+
+- `frontend/src/components/layout/AppSidebar.vue`: modified — skeleton classes, focus-visible, active states, expanded CSS
+- `frontend/src/components/admin/AdminSidebar.vue`: modified — focus-visible, active states, expanded CSS
+- `frontend/src/views/TopicsView.vue`: modified — font-semibold, focus-visible on back button and cards
+- `frontend/src/views/DocumentView.vue`: modified — font-semibold, text-sm panel headings, focus-visible, active states
+- `frontend/src/views/SharedView.vue`: modified — font-semibold
+- `frontend/src/views/SettingsView.vue`: modified — focus-visible on tab buttons and dismiss buttons
+- `frontend/src/views/admin/AdminOverviewView.vue`: modified — text-2xl page title
+- `frontend/src/views/admin/AdminAuditView.vue`: modified — focus-visible and active states on all buttons
+- `frontend/src/views/admin/AdminUsersView.vue`: modified — focus-visible and active states
+- `frontend/src/views/admin/AdminAiView.vue`: modified — focus-visible and active states
+- `frontend/src/components/settings/SettingsAccountTab.vue`: modified — text-sm panel headings, focus-visible, active states
+- `frontend/src/components/settings/SettingsAiTab.vue`: modified — text-lg section title
+- `frontend/src/components/settings/SettingsCloudTab.vue`: modified — text-lg section title, focus-visible, active states
+- `frontend/src/components/settings/SettingsPreferencesTab.vue`: modified — text-lg section title
+- `frontend/src/components/auth/BackupCodesDisplay.vue`: modified — text-lg heading, focus-visible, active
+- `frontend/src/components/cloud/CloudCredentialModal.vue`: modified — text-lg modal title, close button focus-visible
+- `frontend/src/components/documents/DocumentCard.vue`: modified — focus-visible and active on action buttons
+- `frontend/src/components/storage/StorageBrowser.vue`: modified — focus-visible and active on all row action buttons
+- `frontend/src/components/topics/TopicManager.vue`: modified — focus-visible and active on all buttons
+- `frontend/src/components/layout/__tests__/AppSidebar.visual.test.js`: created — 4 tests
+- `frontend/src/views/__tests__/typography.visual.test.js`: created — 3 tests
+- Commit `2af5b7c` exists in git log: confirmed
+- 36 test files, 270 tests all pass: confirmed
+- Build succeeds: confirmed

.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-06-PLAN.md

@@ -0,0 +1,45 @@
+---
+phase: 11-visual-design-responsive-layout-cleanup
+plan: 6
+type: execute
+wave: 5
+depends_on: [11-05]
+requirements: [CODE-07, PERF-02]
+files_modified:
+  - frontend/src/**/*
+  - .planning/perf/phase11-final.html
+  - .planning/perf/phase11-final-summary.md
+  - .planning/phases/11-visual-design-responsive-layout-cleanup/11-VERIFICATION.md
+autonomous: true
+---
+
+# Plan 11-06 — Dead-Code Cleanup & Final Measurement
+
+## Objective
+
+Delete unreferenced frontend code and capture the final bundle report after all Phase 11 optimizations are complete.
+
+## Tasks
+
+1. Run dead-code searches for unreferenced components, stores, helpers, imports, and old route views.
+2. Explicitly classify these known suspects before deleting or retaining:
+   - `frontend/src/views/AccountView.vue` (`/account` currently redirects to `/settings`)
+   - `frontend/src/components/admin/__tests__/AdminAiConfigTab.test.js`
+   - `frontend/src/components/admin/__tests__/AdminQuotasTab.test.js`
+   - `frontend/src/components/admin/__tests__/AdminUsersTab.test.js`
+3. Confirm `HomeView.vue`, `FolderView.vue`, and `AdminView.vue` remain absent.
+4. Delete files with no active route and no active import in the same commit as their references are removed.
+5. Remove unused imports and stale tests that target deleted files; keep behavior tests that still protect live surfaces.
+6. Run the final analyzer build and write `.planning/perf/phase11-final.html`.
+7. Add `.planning/perf/phase11-final-summary.md` comparing baseline vs final bundle size, chunk count, and largest chunks.
+8. Produce `11-VERIFICATION.md` mapping every Phase 11 requirement to code/test/build evidence.
+
+## Acceptance Criteria
+
+- CODE-07 is satisfied: no dead files, unused route components, unused stores, or unused imports remain.
+- Known suspects are each documented as deleted or intentionally retained.
+- Final bundle report and summary are committed under `.planning/perf/`.
+- Baseline and final reports are both present.
+- `cd frontend && npm run test -- --run` passes.
+- `cd frontend && npm run build` passes.
+- Phase 11 verification maps VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, and PERF-03 to concrete evidence.