init

CLAUDE.md

@@ -275,6 +275,8 @@ Obtain JWT: `POST /api/tokens` after HF OAuth login.
 ## Active Technologies
 - Python 3.11+ (backend), TypeScript (frontend) + FastAPI, LlamaIndex, llama-index-llms-google-genai, llama-index-embeddings-google-genai, React 18+, Tailwind CSS, Shadcn/UI (004-gemini-vault-chat)
 - Filesystem vault (existing), LlamaIndex persisted vector store (new, under `data/llamaindex/`) (004-gemini-vault-chat)
+- TypeScript 5.x, React 18+ (006-ui-polish)
+- localStorage for user preferences (font size, TOC panel state) (006-ui-polish)
 
 ## Recent Changes
 - 004-gemini-vault-chat: Added Python 3.11+ (backend), TypeScript (frontend) + FastAPI, LlamaIndex, llama-index-llms-google-genai, llama-index-embeddings-google-genai, React 18+, Tailwind CSS, Shadcn/UI

specs/006-ui-polish/checklists/requirements.md

@@ -0,0 +1,48 @@
+# Specification Quality Checklist: UI Polish Pack
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-11-28
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Validation Results
+
+**Status**: ✅ PASSED - All quality criteria met
+
+**Details**:
+- Specification clearly separates WHAT from HOW
+- All 7 user stories include acceptance scenarios
+- 18 functional requirements are testable and unambiguous
+- 10 success criteria are measurable and technology-agnostic
+- Edge cases address boundary conditions
+- Assumptions document reasonable defaults
+- No clarifications needed (all features well-understood from user input)
+- Priorities clearly assigned (P1, P2, P3, STRETCH)
+
+**Notes**:
+- Specification is ready for `/speckit.plan`
+- No updates required before proceeding to planning phase

specs/006-ui-polish/data-model.md

@@ -0,0 +1,277 @@
+# Data Model: UI Polish Pack
+
+**Feature**: 006-ui-polish
+**Date**: 2025-11-28
+**Type**: Client-side only (no backend/database models)
+
+## Overview
+
+All data for UI polish features is stored client-side in browser localStorage or ephemeral React component state. No backend API changes or database modifications required.
+
+## Entities
+
+### 1. FontSizePreference
+
+**Storage**: localStorage
+**Key**: `note-font-size`
+**Type**: `"small" | "medium" | "large"`
+**Scope**: Global (applies to all notes across sessions)
+
+**Attributes**:
+- `size`: The user's selected font size
+  - `"small"` = 0.875rem (14px)
+  - `"medium"` = 1rem (16px) - default
+  - `"large"` = 1.125rem (18px)
+
+**Lifecycle**:
+- Created: First time user clicks font size button
+- Updated: Each font size change
+- Persisted: Indefinitely (until user clears browser data)
+- Default: `"medium"` if not set
+
+**Usage**:
+```typescript
+// Read
+const savedSize = localStorage.getItem('note-font-size') ?? 'medium';
+
+// Write
+localStorage.setItem('note-font-size', 'large');
+```
+
+---
+
+### 2. TOCPanelState
+
+**Storage**: localStorage
+**Key**: `toc-panel-open`
+**Type**: `boolean`
+**Scope**: Global (persists across sessions)
+
+**Attributes**:
+- `isOpen`: Whether TOC panel is currently visible
+  - `true` = panel expanded
+  - `false` = panel collapsed
+
+**Lifecycle**:
+- Created: First time user clicks TOC button
+- Updated: Each TOC toggle
+- Persisted: Indefinitely
+- Default: `false` (collapsed) if not set
+
+**Usage**:
+```typescript
+// Read
+const isOpen = localStorage.getItem('toc-panel-open') === 'true';
+
+// Write
+localStorage.setItem('toc-panel-open', String(isOpen));
+```
+
+---
+
+### 3. WikilinkPreviewCache
+
+**Storage**: React component state (ephemeral)
+**Type**: `Map<string, string>`
+**Scope**: Component lifecycle (NoteViewer or markdown renderer)
+
+**Attributes**:
+- `key`: Note path (string) - e.g., "guides/Quick Reference.md"
+- `value`: Preview text (string) - first 150-200 characters of note body
+
+**Lifecycle**:
+- Created: Component mount
+- Updated: On first preview fetch for each unique wikilink
+- Cleared: Component unmount
+- Not persisted to localStorage (ephemeral per session)
+
+**Usage**:
+```typescript
+const [previewCache, setPreviewCache] = useState<Map<string, string>>(new Map());
+
+// Check cache
+const cached = previewCache.get(notePath);
+if (cached) return cached;
+
+// Fetch and cache
+const preview = await fetchPreview(notePath);
+setPreviewCache(prev => new Map(prev).set(notePath, preview));
+```
+
+**Rationale for ephemeral storage**:
+- Preview content can change between sessions
+- Avoids stale data in localStorage
+- Cache hit rate still high within single reading session
+
+---
+
+### 4. TOCHeading
+
+**Storage**: Computed (not persisted)
+**Type**: Array of heading objects
+**Scope**: Per-note (recomputed when note.body changes)
+
+**Attributes**:
+- `id`: Slugified heading text for anchor links (string)
+  - Generated via: `text.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '')`
+  - Example: "API Documentation" → "api-documentation"
+- `text`: Raw heading text (string) - e.g., "API Documentation"
+- `level`: Heading depth (1 | 2 | 3)
+  - 1 = H1 (`#`)
+  - 2 = H2 (`##`)
+  - 3 = H3 (`###`)
+  - H4-H6 not included in TOC
+
+**Lifecycle**:
+- Computed: When markdown is rendered via react-markdown
+- Updated: When note.body changes
+- Cached: Via useMemo to avoid re-computation on re-renders
+- Not persisted (derived data)
+
+**Example**:
+```typescript
+const headings: TOCHeading[] = [
+  { id: 'getting-started', text: 'Getting Started', level: 1 },
+  { id: 'installation', text: 'Installation', level: 2 },
+  { id: 'prerequisites', text: 'Prerequisites', level: 3 },
+];
+```
+
+**Usage**:
+```typescript
+const headings = useMemo(() => {
+  const extracted: TOCHeading[] = [];
+  // Extract from markdown during render
+  // (via custom react-markdown heading renderer)
+  return extracted;
+}, [note.body]);
+```
+
+---
+
+## State Management
+
+### Component Hierarchy
+
+```text
+MainApp (root)
+├── fontSize state (localStorage-backed)
+├── DirectoryTree
+│   └── expandAll/collapseAll triggers (ephemeral)
+└── NoteViewer
+    ├── TOC state (localStorage-backed)
+    ├── TOC headings (computed from markdown)
+    └── Wikilink preview cache (ephemeral Map)
+```
+
+### Data Flow
+
+**Font Size**:
+```
+User clicks A+/A-/A
+  ↓
+useFontSize hook updates state
+  ↓
+localStorage.setItem('note-font-size', newSize)
+  ↓
+CSS variable --content-font-size updated
+  ↓
+.prose container text resizes
+```
+
+**TOC**:
+```
+Note body changes
+  ↓
+useTableOfContents extracts headings (useMemo)
+  ↓
+User clicks TOC button
+  ↓
+toggleTOC() updates isOpen state + localStorage
+  ↓
+TableOfContents component renders/hides
+```
+
+**Wikilink Preview**:
+```
+User hovers on [[wikilink]]
+  ↓
+500ms delay
+  ↓
+Check previewCache Map
+  ↓ (cache miss)
+Fetch note via GET /api/notes/{path}
+  ↓
+Extract first 150 chars
+  ↓
+Update cache + display HoverCard
+```
+
+---
+
+## Validation Rules
+
+### FontSizePreference
+- Must be one of: `"small" | "medium" | "large"`
+- If invalid value in localStorage, default to `"medium"`
+
+### TOCPanelState
+- Must be parseable as boolean
+- If invalid value, default to `false`
+
+### TOCHeading.id
+- Must be unique within a note (handle duplicate headings)
+- Must be valid HTML ID (a-z, 0-9, -, _)
+- If duplicate heading text, append `-2`, `-3`, etc.
+
+---
+
+## Performance Considerations
+
+### LocalStorage Access
+- Read once on component mount
+- Write only on user action (not on every render)
+- Max size: ~5MB per domain (plenty for small preference values)
+
+### Wikilink Cache
+- Map lookups are O(1) - efficient
+- Cleared on unmount to avoid memory leaks
+- Max realistic size: ~50 previews × 200 chars = ~10KB
+
+### TOC Extraction
+- useMemo prevents re-computation on unrelated re-renders
+- Only recomputes when note.body changes
+- Max realistic cost: 50 headings × minimal parsing = <10ms
+
+---
+
+## Migration Notes
+
+**No migrations required** - All data is client-side and newly created.
+
+If user has existing localStorage data:
+- New keys (`note-font-size`, `toc-panel-open`) won't conflict
+- Existing keys (e.g., `tts-volume`) unaffected
+
+---
+
+## Relationships
+
+No relationships between entities - each is independent:
+- Font size doesn't affect TOC
+- TOC state doesn't affect preview cache
+- All features operate independently
+
+---
+
+## Summary
+
+| Entity | Storage | Persisted | Scope | Size |
+|--------|---------|-----------|-------|------|
+| FontSizePreference | localStorage | Yes | Global | ~10 bytes |
+| TOCPanelState | localStorage | Yes | Global | ~5 bytes |
+| WikilinkPreviewCache | React state | No | Component | ~10 KB |
+| TOCHeading | Computed | No | Per-note | Negligible |
+
+**Total localStorage footprint**: ~15 bytes (negligible)
+**Total memory footprint**: ~10 KB (preview cache)

specs/006-ui-polish/plan.md

@@ -0,0 +1,339 @@
+# Implementation Plan: UI Polish Pack
+
+**Branch**: `006-ui-polish` | **Date**: 2025-11-28 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/006-ui-polish/spec.md`
+
+## Summary
+
+This feature adds seven quick-win UX enhancements to improve the document viewer's polish and usability for hackathon demo. All features are frontend-only with no backend changes required. Implementation uses existing patterns (CSS variables, tailwindcss-animate, React hooks, shadcn/ui components) to minimize complexity and maintain consistency.
+
+**Primary Requirements**:
+- P1: Font size adjuster (3 sizes: small/medium/large)
+- P1: Expand/collapse all folders in directory tree
+- P2: Wikilink preview tooltips on hover
+- P2: Reading time estimator badge
+- P2: Table of contents flyout panel
+- P3: Smooth transitions/animations
+- STRETCH: Particle click effects
+
+**Technical Approach**: Leverage existing architecture (CSS custom properties for font sizing, state propagation for tree expansion, HoverCard for previews, ResizablePanel for TOC, tailwindcss-animate for transitions). Zero backend changes, minimal new dependencies.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.x, React 18+
+**Primary Dependencies**:
+- React 18, TypeScript, Vite (existing)
+- Tailwind CSS + tailwindcss-animate (existing)
+- shadcn/ui components (existing)
+- react-markdown + remark-gfm (existing)
+- NEW: @radix-ui/react-hover-card (for wikilink previews)
+
+**Storage**: localStorage for user preferences (font size, TOC panel state)
+**Testing**: Manual verification + browser console (no automated tests for UI polish)
+**Target Platform**: Modern browsers (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
+**Project Type**: Web (frontend-only changes)
+**Performance Goals**:
+- Font size change: < 100ms
+- Expand All (100 folders): < 2s
+- Wikilink preview fetch: < 600ms total (500ms delay + 100ms fetch)
+- TOC generation: < 500ms for 50 headings
+- All animations: 60 FPS (no dropped frames)
+
+**Constraints**:
+- WCAG 2.2 Level AA compliance
+- No backend API changes
+- No new data models or database changes
+- Respect prefers-reduced-motion media query
+- Mobile-friendly (responsive design)
+
+**Scale/Scope**:
+- 7 features (6 core + 1 stretch)
+- 18 functional requirements
+- Est. 4-6 hours implementation
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+### I. Brownfield Integration ✅ PASS
+
+**Assessment**: All features leverage existing patterns and components. No rewrites or refactors required.
+
+**Evidence**:
+- Font sizing uses existing CSS custom properties pattern (`index.css:6-50`)
+- Tree expansion extends existing DirectoryTree component (`DirectoryTree.tsx`)
+- Tooltips use shadcn/ui (existing component library)
+- TOC uses existing ResizablePanel pattern (`MainApp.tsx:583-778`)
+- Transitions use existing tailwindcss-animate (`tailwind.config.js:57-97`)
+- Reading time uses existing markdownToPlainText (`markdownToText.ts`)
+
+### II. Test-Backed Development ⚠️ PARTIAL
+
+**Assessment**: Frontend UI polish features rely on manual verification. No automated tests required per constitution ("UI components rely on manual verification/E2E").
+
+**Evidence**:
+- Spec includes detailed acceptance scenarios for manual testing
+- No backend changes = no pytest requirements
+- Frontend E2E tests not in scope for polish features
+- Regression: Existing tests unaffected (no changes to tested code paths)
+
+### III. Incremental Delivery ✅ PASS
+
+**Assessment**: Features are independently testable and can be implemented/deployed incrementally.
+
+**Evidence**:
+- Spec prioritizes features (P1, P2, P3, STRETCH)
+- Each feature in separate component/file
+- No interdependencies between features
+- Can ship P1 features first, P2/P3 later
+
+### IV. Specification-Driven ✅ PASS
+
+**Assessment**: All work traces back to spec.md with clear functional requirements.
+
+**Evidence**:
+- 18 functional requirements (FR-001 through FR-018)
+- Each feature has acceptance scenarios
+- Success criteria defined
+- No ghost features planned
+
+**RESULT**: ✅ **APPROVED FOR IMPLEMENTATION** - All gates pass or justified
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/006-ui-polish/
+├── spec.md               # Feature specification
+├── plan.md               # This file
+├── research.md           # Technology decisions and best practices
+├── checklists/
+│   └── requirements.md   # Spec quality validation
+└── tasks.md              # Will be generated by /speckit.tasks
+```
+
+### Source Code (repository root)
+
+```text
+frontend/
+├── src/
+│   ├── components/
+│   │   ├── DirectoryTree.tsx          # Modified: add expand/collapse all
+│   │   ├── NoteViewer.tsx             # Modified: add font controls, reading time, TOC button
+│   │   ├── TableOfContents.tsx        # NEW: TOC panel component
+│   │   └── ui/
+│   │       ��── hover-card.tsx         # NEW: shadcn component (via CLI)
+│   │       └── slider.tsx             # Existing: used for font size
+│   ├── pages/
+│   │   └── MainApp.tsx                # Modified: font size state, smooth transitions
+│   ├── lib/
+│   │   ├── markdown.tsx               # Modified: add heading IDs, wikilink HoverCard
+│   │   └── markdownToText.ts          # Existing: used for reading time
+│   ├── hooks/
+│   │   ├── useFontSize.ts             # NEW: font size preference hook
+│   │   └── useTableOfContents.ts      # NEW: TOC extraction hook
+│   └── index.css                      # Modified: add --content-font-size variable
+└── tailwind.config.js                 # Modified: extend transition utilities
+
+backend/
+└── [NO CHANGES]
+
+data/
+└── [NO CHANGES]
+```
+
+**Structure Decision**: Web application (Option 2) - Frontend-only changes. All modifications confined to `frontend/src/`. No backend, API, or database changes required.
+
+## Complexity Tracking
+
+**No violations to justify** - All constitution gates pass.
+
+## Phase 0: Research (COMPLETE)
+
+**Output**: `research.md` - See [research.md](./research.md)
+
+**Key Decisions**:
+1. **Font Size**: CSS custom properties scoped to `.prose` (WCAG compliant)
+2. **Expand/Collapse**: State propagation via `forceExpandState` prop
+3. **Wikilink Previews**: shadcn HoverCard with 500ms delay + cache
+4. **TOC**: Custom react-markdown renderer + ResizablePanel
+5. **Transitions**: tailwindcss-animate (existing)
+6. **Reading Time**: markdownToPlainText + 200 WPM
+7. **Particles**: CSS-only or shadcn component (stretch)
+
+**Resolved Clarifications**: None - all technical approaches clear from research.
+
+## Phase 1: Design & Contracts
+
+### Data Model
+
+**File**: `data-model.md`
+
+**Entities**:
+
+1. **FontSizePreference** (localStorage)
+   - Key: `note-font-size`
+   - Value: `"small"` | `"medium"` | `"large"`
+   - Scope: Global (applies to all notes)
+
+2. **TOCPanelState** (localStorage)
+   - Key: `toc-panel-open`
+   - Value: `boolean`
+   - Scope: Global (persists across sessions)
+
+3. **WikilinkPreviewCache** (React state)
+   - Type: `Map<string, string>` (path → preview text)
+   - Lifecycle: Component mount (cleared on unmount)
+   - Purpose: Avoid re-fetching previews
+
+4. **TOCHeading** (computed)
+   - Fields: `{ id: string, text: string, level: 1|2|3 }`
+   - Source: Extracted from markdown during render
+   - Lifecycle: Re-computed when note.body changes
+
+**No backend data models** - All state is client-side.
+
+### API Contracts
+
+**No new API endpoints** - Features use existing endpoints:
+
+- `GET /api/notes/{path}` - Fetch note for wikilink preview (existing)
+- All other features are pure frontend (no API calls)
+
+### Component Contracts
+
+**New Components**:
+
+1. **TableOfContents.tsx**
+```typescript
+interface TableOfContentsProps {
+  headings: TOCHeading[];
+  isOpen: boolean;
+  onToggle: () => void;
+  onHeadingClick: (id: string) => void;
+}
+```
+
+2. **useFontSize.ts**
+```typescript
+interface UseFontSizeReturn {
+  fontSize: "small" | "medium" | "large";
+  setFontSize: (size: "small" | "medium" | "large") => void;
+  fontSizeRem: number; // 0.875 | 1 | 1.125
+}
+```
+
+3. **useTableOfContents.ts**
+```typescript
+interface UseTableOfContentsReturn {
+  headings: TOCHeading[];
+  isOpen: boolean;
+  toggleTOC: () => void;
+  scrollToHeading: (id: string) => void;
+}
+```
+
+**Modified Components**:
+
+1. **DirectoryTree.tsx**
+```typescript
+// Add props:
+interface DirectoryTreeProps {
+  // ... existing props
+  expandAll?: boolean; // Trigger expand all
+  collapseAll?: boolean; // Trigger collapse all
+}
+```
+
+2. **NoteViewer.tsx**
+```typescript
+// Add props:
+interface NoteViewerProps {
+  // ... existing props
+  fontSize?: "small" | "medium" | "large";
+  onFontSizeChange?: (size: "small" | "medium" | "large") => void;
+}
+```
+
+### Quick Start Guide
+
+**File**: `quickstart.md`
+
+**Development Setup**:
+```bash
+# 1. Switch to feature branch
+git checkout 006-ui-polish
+
+# 2. Install new shadcn component
+cd frontend
+npx shadcn@latest add hover-card
+
+# 3. Start dev server
+npm run dev
+
+# 4. Test in browser at http://localhost:5173
+```
+
+**Testing Checklist**:
+- [ ] Font size: Click A-, A, A+ buttons and verify text resizes
+- [ ] Font persistence: Reload page and verify size retained
+- [ ] Expand All: Click and verify all folders open
+- [ ] Collapse All: Click and verify all folders close
+- [ ] Wikilink preview: Hover over `[[link]]` for 500ms, see tooltip
+- [ ] Reading time: Open long note, see "X min read" badge
+- [ ] TOC: Open long note, click TOC button, see headings panel
+- [ ] TOC scroll: Click heading in TOC, verify smooth scroll
+- [ ] Transitions: Switch notes, verify fade-in animation
+- [ ] Accessibility: Tab through controls, verify keyboard nav
+- [ ] Mobile: Test on small screen, verify responsive
+
+**Deployment**:
+```bash
+# Build production bundle
+npm run build
+
+# Verify build output
+ls -lh dist/
+
+# Deploy (HuggingFace Space auto-deploys on git push)
+git push origin 006-ui-polish
+```
+
+## Constitution Re-Check (Post-Design)
+
+All gates remain **PASS** after design phase:
+
+- ✅ Brownfield: No existing code rewritten
+- ✅ Testing: Manual verification per constitution
+- ✅ Incremental: Features independently deployable
+- ✅ Spec-driven: All work traces to FR-001 through FR-018
+
+**No new violations introduced.**
+
+## Technology Additions
+
+**New Dependencies**:
+- `@radix-ui/react-hover-card` (via shadcn CLI)
+
+**Optional (Stretch)**:
+- shadcn particles component (if particle effects implemented)
+
+## Next Steps
+
+1. Run `/speckit.tasks` to generate implementation task list
+2. Implement features in priority order (P1 → P2 → P3 → STRETCH)
+3. Manual testing per quickstart.md checklist
+4. Merge to master when P1+P2 features complete (P3+STRETCH optional)
+
+## Files Generated
+
+- ✅ `research.md` - Technology decisions and best practices
+- ✅ `data-model.md` - Client-side data structures
+- ✅ `quickstart.md` - Development and testing guide
+- ⏳ `contracts/` - N/A (no API contracts, component contracts in plan.md)
+- ⏳ `tasks.md` - To be generated by `/speckit.tasks`
+
+---
+
+**Plan Status**: ✅ COMPLETE - Ready for `/speckit.tasks`

specs/006-ui-polish/quickstart.md

@@ -0,0 +1,348 @@
+# Quick Start Guide: UI Polish Pack
+
+**Feature**: 006-ui-polish
+**Branch**: `006-ui-polish`
+**Estimated Time**: 4-6 hours implementation
+
+## Prerequisites
+
+- Node.js 18+ and npm
+- Git
+- Code editor (VS Code recommended)
+- Modern browser (Chrome/Firefox/Safari/Edge)
+
+## Development Setup
+
+### 1. Check Out Feature Branch
+
+```bash
+# Ensure you're in project root
+cd /home/wolfe/Projects/Document-MCP
+
+# Check out feature branch
+git checkout 006-ui-polish
+
+# Verify branch
+git branch --show-current
+# Should show: 006-ui-polish
+```
+
+### 2. Install Dependencies
+
+```bash
+# Navigate to frontend
+cd frontend
+
+# Install new shadcn/ui component for wikilink previews
+npx shadcn@latest add hover-card
+
+# Verify installation
+ls src/components/ui/hover-card.tsx
+# Should exist
+
+# Return to project root
+cd ..
+```
+
+### 3. Start Development Server
+
+```bash
+# Start frontend dev server
+cd frontend
+npm run dev
+
+# Server starts at http://localhost:5173
+# Open in browser to begin testing
+```
+
+### 4. Verify Existing Features
+
+Before implementing polish features, verify baseline functionality:
+
+- [ ] Notes load and display correctly
+- [ ] Directory tree shows folders and files
+- [ ] Clicking notes navigates successfully
+- [ ] Wikilinks render and are clickable
+- [ ] TTS controls work (if available)
+
+## Implementation Order
+
+Follow priority order from spec:
+
+### Phase 1: P1 Features (Core)
+
+1. **Font Size Adjuster** (~15 min)
+   - Files: `frontend/src/index.css`, `frontend/src/hooks/useFontSize.ts`, `frontend/src/components/NoteViewer.tsx`
+   - Test: Click A-/A/A+ buttons, verify text resizes
+
+2. **Expand/Collapse All** (~20 min)
+   - Files: `frontend/src/components/DirectoryTree.tsx`, `frontend/src/pages/MainApp.tsx`
+   - Test: Click "Expand All" / "Collapse All" buttons
+
+### Phase 2: P2 Features (Important)
+
+3. **Reading Time Estimator** (~10 min)
+   - Files: `frontend/src/components/NoteViewer.tsx`
+   - Test: Open notes of varying lengths, verify badge appears
+
+4. **Wikilink Preview Tooltips** (~30 min)
+   - Files: `frontend/src/lib/markdown.tsx`, `frontend/src/components/ui/hover-card.tsx`
+   - Test: Hover over `[[wikilink]]` for 500ms, see preview
+
+5. **Table of Contents** (~40 min)
+   - Files: `frontend/src/hooks/useTableOfContents.ts`, `frontend/src/components/TableOfContents.tsx`, `frontend/src/components/NoteViewer.tsx`
+   - Test: Open long note, click TOC button, navigate headings
+
+### Phase 3: P3 Features (Polish)
+
+6. **Smooth Transitions** (~10 min)
+   - Files: `frontend/tailwind.config.js`, `frontend/src/pages/MainApp.tsx`
+   - Test: Switch notes, toggle views, verify animations
+
+### Phase 4: Stretch (Optional)
+
+7. **Particle Effects** (~45 min + tuning)
+   - Files: CSS or shadcn particles component
+   - Test: Click UI elements, verify no lag
+
+## Testing Checklist
+
+Use this checklist during development and before deployment:
+
+### Font Size Adjuster
+
+- [ ] **A+ button**: Text increases to 18px
+- [ ] **A- button**: Text decreases to 14px
+- [ ] **A button**: Text resets to 16px (default)
+- [ ] **Persistence**: Reload page, verify size retained
+- [ ] **Scope**: Only note body text resizes (not UI chrome)
+- [ ] **Accessibility**: Can tab to buttons with keyboard
+- [ ] **Mobile**: Buttons visible and tappable on small screen
+
+### Expand/Collapse All
+
+- [ ] **Expand All**: All folders open, showing contents
+- [ ] **Collapse All**: All folders close, hiding contents
+- [ ] **Mixed state**: Works correctly when some folders already open
+- [ ] **Performance**: Completes in < 2s for 100+ folders
+- [ ] **Visual feedback**: Buttons show active state
+- [ ] **Accessibility**: Keyboard navigable
+
+### Wikilink Preview Tooltips
+
+- [ ] **500ms delay**: Tooltip appears after hovering 500ms
+- [ ] **Preview content**: Shows first 150-200 characters
+- [ ] **Mouse away**: Tooltip disappears when mouse moves away
+- [ ] **Broken link**: Shows "Note not found" for invalid links
+- [ ] **No flickering**: Quick mouse movement doesn't trigger tooltips
+- [ ] **Cache**: Second hover on same link is instant
+- [ ] **Accessibility**: Wikilinks still keyboard navigable
+
+### Reading Time Estimator
+
+- [ ] **Badge appears**: Shows "X min read" for notes > 200 words
+- [ ] **No badge**: Hidden for very short notes (< 200 words)
+- [ ] **Accuracy**: Estimates reasonable (within ±20% of actual)
+- [ ] **Position**: Badge near note title, visually balanced
+- [ ] **Mobile**: Badge visible on small screens
+
+### Table of Contents
+
+- [ ] **TOC button**: Appears in note toolbar
+- [ ] **Panel opens**: Clicking button shows TOC sidebar
+- [ ] **Headings listed**: H1, H2, H3 shown with indentation
+- [ ] **Click to scroll**: Clicking heading scrolls to section
+- [ ] **Smooth scroll**: Scrolling is smooth (not instant)
+- [ ] **Close panel**: Clicking button again or outside closes panel
+- [ ] **Persistence**: Panel state retained after reload
+- [ ] **Empty state**: Shows "No headings found" for notes without headings
+- [ ] **Performance**: Generates TOC in < 500ms for 50 headings
+- [ ] **Mobile**: Panel overlays content, doesn't break layout
+
+### Smooth Transitions
+
+- [ ] **Note switch**: New note fades in over 300ms
+- [ ] **Graph toggle**: Graph slides in over 250ms
+- [ ] **Tree selection**: Selected item highlights smoothly
+- [ ] **60 FPS**: No dropped frames or jank
+- [ ] **Reduced motion**: Respects `prefers-reduced-motion` setting
+
+### Particle Effects (Stretch)
+
+- [ ] **Click feedback**: Particles appear on click
+- [ ] **Performance**: No lag or frame drops
+- [ ] **Multiple clicks**: Handles rapid clicking gracefully
+- [ ] **Reduced motion**: Disabled when user prefers reduced motion
+- [ ] **Mobile**: Disabled on mobile or optimized
+
+## Browser Testing
+
+Test in multiple browsers:
+
+- [ ] Chrome/Chromium (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (if on macOS)
+- [ ] Edge (latest)
+- [ ] Mobile Safari (iOS)
+- [ ] Mobile Chrome (Android)
+
+## Performance Verification
+
+Use browser DevTools to verify performance:
+
+### Chrome DevTools Performance
+
+1. Open DevTools → Performance tab
+2. Click Record
+3. Test feature (e.g., click font size button)
+4. Stop recording
+5. Verify:
+   - [ ] No long tasks (> 50ms)
+   - [ ] 60 FPS maintained
+   - [ ] No layout thrashing
+
+### Memory Profiling
+
+1. Open DevTools → Memory tab
+2. Take heap snapshot before testing
+3. Use features extensively
+4. Take heap snapshot after
+5. Verify:
+   - [ ] No memory leaks
+   - [ ] Preview cache clears on unmount
+   - [ ] localStorage usage minimal (< 1KB)
+
+## Build & Deploy
+
+### Local Build
+
+```bash
+# Build production bundle
+cd frontend
+npm run build
+
+# Expected output:
+# - dist/ directory created
+# - Assets minified and optimized
+# - No TypeScript errors
+# - No linting errors
+
+# Verify build output
+ls -lh dist/
+# Should show:
+# - index.html
+# - assets/ (JS/CSS chunks)
+# - Total size ~400-500KB gzipped
+```
+
+### Preview Production Build
+
+```bash
+# Serve production build locally
+npm run preview
+
+# Open http://localhost:4173
+# Test all features in production mode
+```
+
+### Deploy to HuggingFace Space
+
+```bash
+# Ensure all changes committed
+git status
+# Should show clean working tree
+
+# Push to remote
+git push origin 006-ui-polish
+
+# HuggingFace Space auto-deploys from git
+# Monitor build logs in Space settings
+# Deployment takes ~3-5 minutes
+```
+
+## Troubleshooting
+
+### HoverCard Not Found
+
+**Error**: `Cannot find module '@/components/ui/hover-card'`
+
+**Solution**:
+```bash
+cd frontend
+npx shadcn@latest add hover-card
+```
+
+### Font Size Not Applying
+
+**Error**: Font size changes don't affect text
+
+**Solution**:
+- Check `--content-font-size` CSS variable in index.css
+- Verify `.prose` class applied to note body
+- Check browser console for CSS errors
+
+### TOC Not Extracting Headings
+
+**Error**: TOC panel shows "No headings found" but note has headings
+
+**Solution**:
+- Verify headings use markdown syntax (#, ##, ###)
+- Check custom renderer in markdown.tsx
+- Check browser console for extraction errors
+
+### Animations Janky
+
+**Error**: Transitions stutter or drop frames
+
+**Solution**:
+- Use transform/opacity only (not width/height)
+- Check for layout thrashing in DevTools
+- Reduce animation duration or complexity
+
+### LocalStorage Not Persisting
+
+**Error**: Preferences lost on reload
+
+**Solution**:
+- Check browser doesn't have localStorage disabled
+- Verify localStorage.setItem() calls succeed
+- Check browser console for quota errors
+
+## Rollback Plan
+
+If issues arise in production:
+
+```bash
+# Revert to previous working state
+git checkout master
+
+# Or revert specific commit
+git revert <commit-hash>
+
+# Push to trigger redeployment
+git push origin master
+```
+
+## Next Steps
+
+After implementation and testing:
+
+1. Run `/speckit.tasks` to generate detailed task breakdown
+2. Implement features in priority order
+3. Manual test after each feature
+4. Commit incrementally (one feature per commit)
+5. Merge to master when P1+P2 complete
+6. Deploy to production
+7. Monitor for issues
+
+## Support Resources
+
+- [React Docs](https://react.dev)
+- [Tailwind CSS Docs](https://tailwindcss.com/docs)
+- [shadcn/ui Components](https://ui.shadcn.com)
+- [react-markdown Docs](https://github.com/remarkjs/react-markdown)
+- [WCAG 2.2 Guidelines](https://www.w3.org/WAI/WCAG22/quickref/)
+
+---
+
+**Ready to Start**: All setup complete, begin with P1 features! 🚀

specs/006-ui-polish/research.md

@@ -0,0 +1,312 @@
+# Research: UI Polish Pack Implementation
+
+**Feature**: 006-ui-polish
+**Date**: 2025-11-28
+**Researcher**: Explore Agent (Sonnet 4.5)
+
+## 1. Font Size Adjuster
+
+**Decision**: CSS Custom Properties (CSS Variables) scoped to content area
+
+**Rationale**:
+- WCAG 2.2 compliance requires text scalable to 200% without loss of functionality
+- CSS custom properties provide centralized control and easy dynamic updates
+- Existing codebase already uses CSS variables for theming
+- Avoids inline styles and className switching complexity
+
+**Implementation Details**:
+- Add CSS variable `--content-font-size` to `:root`
+- Apply to `.prose` container (already used in NoteViewer.tsx:150)
+- Range: 0.875rem (14px small), 1rem (16px medium), 1.125rem (18px large)
+- Persist to localStorage key `note-font-size`
+- Use rem units (relative to root) for scalability
+
+**Alternatives Considered**:
+- Inline styles: Too scattered, hard to maintain
+- className switching: Limited to predefined sizes
+- Browser zoom: Affects entire page including UI chrome
+
+**Code References**:
+- CSS variables: `frontend/src/index.css:6-50`
+- Prose container: `frontend/src/components/NoteViewer.tsx:150`
+- Slider pattern: `frontend/src/components/ui/slider.tsx`
+- TTS volume pattern: `frontend/src/components/NoteViewer.tsx:115-130`
+
+---
+
+## 2. Directory Tree Expand/Collapse
+
+**Decision**: Global expand/collapse state management in DirectoryTree component
+
+**Rationale**:
+- Current implementation uses local `isOpen` state per folder
+- Auto-expands first 2 levels (depth < 2)
+- Pattern already established, needs propagation mechanism
+
+**Implementation Details**:
+- Add buttons above directory tree: "Expand All" / "Collapse All"
+- Add `forceExpandState` prop (undefined | boolean) to TreeNodeItem
+- Override local `isOpen` when `forceExpandState` is set
+- Reset to undefined after 300ms transition
+- Leverage existing `buildTree()` structure
+
+**Pattern**:
+```typescript
+const [expandAllState, setExpandAllState] = useState<boolean | undefined>(undefined);
+const effectiveIsOpen = forceExpandState ?? isOpen;
+```
+
+**Alternatives Considered**:
+- Fully controlled component: More complex, loses local state
+- Context API: Overkill for simple toggle
+- Recursive traversal: Already supported by tree structure
+
+**Code References**:
+- Folder state: `frontend/src/components/DirectoryTree.tsx:97`
+- Tree building: `frontend/src/components/DirectoryTree.tsx:29-86`
+- Folder rendering: `frontend/src/components/DirectoryTree.tsx:134-173`
+
+---
+
+## 3. Wikilink Preview Tooltips
+
+**Decision**: Use shadcn/ui HoverCard with 500ms delay
+
+**Rationale**:
+- HoverCard supports rich content vs Tooltip (simple text)
+- 500ms delay prevents flickering during cursor movement
+- Designed specifically for link previews
+- Existing wikilink handling in markdown.tsx
+
+**Implementation Details**:
+- Install: `npx shadcn@latest add hover-card`
+- Wrap wikilink spans with HoverCard component
+- Set `openDelay={500}` and `closeDelay={100}`
+- Fetch first 200 characters of target note body
+- Cache previews in React.useMemo
+- Show loading skeleton during fetch
+
+**Cache Strategy**:
+```typescript
+const [previewCache, setPreviewCache] = useState<Map<string, string>>(new Map());
+```
+
+**Accessibility Note**:
+- HoverCard is hover-only (not keyboard accessible)
+- Ensure wikilinks remain clickable and keyboard navigable
+
+**Alternatives Considered**:
+- Tooltip: Too limited for content
+- Popover: Requires click, disrupts flow
+- Custom implementation: More work, less accessible
+
+**Code References**:
+- Wikilink component: `frontend/src/lib/markdown.tsx:16-44`
+- Note fetching: `frontend/src/services/api.ts` (getNote)
+
+---
+
+## 4. Table of Contents
+
+**Decision**: Extract headings via custom react-markdown renderer, render in collapsible sidebar
+
+**Rationale**:
+- react-markdown already parses headings
+- Can intercept rendering to extract TOC data
+- ResizablePanel pattern matches existing architecture
+- Smooth scrolling with prefers-reduced-motion support
+
+**Implementation Details**:
+- Add ID generation to h1-h6 renderers
+- Slugify: `text.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '')`
+- Extract: `{ id, text, level }[]` using useRef
+- Render in ResizablePanel (right sidebar)
+- Smooth scroll:
+```typescript
+const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+element.scrollIntoView({ behavior: prefersReducedMotion ? 'auto' : 'smooth' });
+```
+
+**Panel Pattern**:
+- Button in NoteViewer header (near TTS)
+- Default collapsed, opens on click
+- Hierarchical indentation by heading level
+- Persist state to localStorage
+
+**Alternatives Considered**:
+- Sheet component: Not in codebase, needs installation
+- Dialog: Blocks content, poor UX
+- Inline floating: Overlaps on small screens
+
+**Code References**:
+- Heading renderers: `frontend/src/lib/markdown.tsx:61-75`
+- ResizablePanel: `frontend/src/components/NoteEditor.tsx:8`
+- Three-panel layout: `frontend/src/pages/MainApp.tsx:583-778`
+
+---
+
+## 5. Smooth Transitions
+
+**Decision**: CSS transitions with tailwindcss-animate
+
+**Rationale**:
+- Already using `tailwindcss-animate` plugin
+- 60fps GPU-accelerated performance
+- No JavaScript overhead
+- Existing animations: fade-in, slide-in-up, etc.
+- Framer Motion adds 90KB - unnecessary
+
+**Implementation Details**:
+- Extend tailwind.config.js keyframes
+- Add transition utilities:
+```css
+transition: {
+  'smooth': 'all 0.3s cubic-bezier(0.34, 1.56, 0.64, 1)',
+  'fade': 'opacity 0.2s ease-in-out',
+}
+```
+- Apply via className
+- Animate only transform/opacity (GPU properties)
+
+**Performance Rules**:
+- AVOID: margin, padding, border, width, height (causes reflow)
+- USE: transform, opacity only
+- Use `will-change` sparingly
+
+**Alternatives Considered**:
+- Framer Motion: 90KB, complex API
+- React Spring: Physics-based, unnecessary
+- GSAP: 50KB, license issues
+
+**Code References**:
+- Existing animations: `frontend/tailwind.config.js:57-97`
+- Usage: `frontend/src/components/NoteViewer.tsx:79-163`
+- Package: `package.json:61` (tailwindcss-animate)
+
+---
+
+## 6. Reading Time Estimation
+
+**Decision**: Calculate from markdown using markdownToPlainText, 200 WPM standard
+
+**Rationale**:
+- Industry standard: 200 WPM (conservative)
+- Existing utility strips formatting
+- Simple: `Math.ceil(wordCount / 200)`
+- Display as Badge near title
+
+**Implementation Details**:
+- Use `markdownToPlainText(note.body)`
+- Word count: `plainText.trim().split(/\s+/).length`
+- Format: "X min read"
+- Location: After note title (NoteViewer.tsx:82-83)
+- Cache in useMemo
+
+**Pattern**:
+```typescript
+const readingTime = useMemo(() => {
+  const plainText = markdownToPlainText(note.body);
+  const wordCount = plainText.trim().split(/\s+/).length;
+  const minutes = Math.ceil(wordCount / 200);
+  return minutes >= 1 ? `${minutes} min read` : null;
+}, [note.body]);
+```
+
+**Alternatives Considered**:
+- reading-time npm: Overkill
+- 238/250 WPM: Less conservative
+- Character-based: Less accurate
+
+**Code References**:
+- markdownToPlainText: `frontend/src/lib/markdownToText.ts`
+- Badge: `frontend/src/components/ui/badge.tsx`
+- Header: `frontend/src/components/NoteViewer.tsx:79-146`
+
+---
+
+## 7. Particle Effects (Stretch)
+
+**Decision**: CSS-only particles OR shadcn particles component
+
+**Rationale**:
+- CSS-only: Zero bundle, 60fps
+- shadcn has Particles component (installable)
+- Decorative only - no core impact
+- Must respect prefers-reduced-motion
+
+**Implementation Options**:
+
+**Option A: CSS-Only (Recommended)**
+- @keyframes with transform/opacity
+- Multiple elements, staggered delays
+- Box-shadow for many particles
+- Low z-index, pointer-events: none
+
+**Option B: shadcn Particles**
+- Install: `npx shadcn@latest add particles`
+- Limit 50-100 particles max
+- Disable on mobile
+
+**Performance Mitigation**:
+- Max 50 particles
+- Transform-only animations
+- Disable on mobile (media query)
+- Respect prefers-reduced-motion
+- Optional/opt-in feature
+
+**When to Use**:
+- Success celebrations
+- Easter eggs
+- Optional backgrounds
+
+**When NOT to Use**:
+- During reading
+- On lower-end devices
+- By default in production
+
+**Alternatives Considered**:
+- Lottie: Large files
+- Canvas particles: Complex
+- WebGL: Massive overkill
+
+**Code References**:
+- shadcn particles: Available via CLI
+- Animations: `frontend/tailwind.config.js:57-97`
+- Settings: `frontend/src/pages/Settings.tsx` (toggle location)
+
+---
+
+## Technology Decisions Summary
+
+| Feature | Technology | Rationale |
+|---------|-----------|-----------|
+| Font Size | CSS Custom Properties | WCAG compliance, existing pattern |
+| Expand/Collapse | State propagation | Matches existing architecture |
+| Wikilink Preview | shadcn HoverCard | Rich content, accessibility |
+| Table of Contents | Custom renderer + ResizablePanel | Existing markdown/layout patterns |
+| Transitions | tailwindcss-animate | Already installed, performant |
+| Reading Time | markdownToPlainText + 200 WPM | Industry standard, simple |
+| Particles | CSS-only or shadcn | Zero/minimal bundle impact |
+
+## Dependencies to Add
+
+- `hover-card` (shadcn/ui component) - for wikilink previews
+- `particles` (optional, stretch goal) - for particle effects
+
+## Performance Targets
+
+- Font size change: < 100ms
+- Expand All (100 folders): < 2s
+- Wikilink preview: < 600ms (500ms delay + 100ms fetch)
+- TOC generation: < 500ms (50 headings)
+- All animations: 60 FPS
+- No layout thrashing or jank
+
+## Accessibility Compliance
+
+- WCAG 2.2 Level AA compliance
+- Text scalable to 200%
+- Keyboard navigation support
+- prefers-reduced-motion respect
+- ARIA labels on controls
+- Minimum touch target: 24x24px

specs/006-ui-polish/spec.md

@@ -0,0 +1,191 @@
+# Feature Specification: UI Polish Pack
+
+**Feature Branch**: `006-ui-polish`
+**Created**: 2025-11-28
+**Status**: Draft
+**Input**: User description: "Font size adjuster, small, medium (default), and large. Smooth transitions. I am also thinking particle effects when clicking on something, lets put this as a stretch goal as it might be buggy to do right. Expand and collapse all folders button. Wikilink preview tooltip. Reading time estimator. Table of contents as a fly out pane."
+
+## User Scenarios & Testing
+
+### User Story 1 - Adjust Reading Comfort (Priority: P1)
+
+As a user with vision preferences or accessibility needs, I want to adjust the font size of note content so that I can read documentation comfortably without straining my eyes or using browser zoom.
+
+**Why this priority**: Accessibility is critical and affects all users reading notes. This is the simplest feature to implement and delivers immediate value independently.
+
+**Independent Test**: Can be fully tested by opening any note, clicking the font size buttons (A-, A, A+), and verifying text resizes. Delivers immediate reading comfort value without requiring other features.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am viewing a note, **When** I click the "A+" button, **Then** the note body text increases to large size (18px) and my preference is saved
+2. **Given** I am viewing a note with large text, **When** I click the "A-" button, **Then** the note body text decreases to small size (14px)
+3. **Given** I have set a font size preference, **When** I navigate to a different note or refresh the page, **Then** my font size preference is retained
+4. **Given** I am viewing a note, **When** I click the "A" button, **Then** the note body text resets to default size (16px)
+
+---
+
+### User Story 2 - Navigate Large Documentation Structures (Priority: P1)
+
+As a user working with a vault containing many nested folders, I want to quickly expand all folders or collapse them all so that I can find notes faster without manually clicking each folder.
+
+**Why this priority**: Critical for usability in large vaults. Users with 50+ notes in nested folders waste significant time navigating. Can be tested independently by creating a test vault with nested folders.
+
+**Independent Test**: Can be fully tested by creating a vault with 3+ levels of nested folders, clicking "Expand All" to see entire tree, then "Collapse All" to hide all folders. Delivers navigation efficiency value independently.
+
+**Acceptance Scenarios**:
+
+1. **Given** I have a vault with multiple nested folders, **When** I click "Expand All", **Then** all folder nodes in the directory tree expand to show their contents
+2. **Given** all folders are expanded, **When** I click "Collapse All", **Then** all folder nodes close, hiding their contents
+3. **Given** some folders are expanded and some collapsed, **When** I click "Expand All", **Then** all folders expand regardless of their previous state
+4. **Given** I have folders expanded, **When** I click "Collapse All", **Then** the tree returns to showing only top-level items
+
+---
+
+### User Story 3 - Preview Note Content Without Navigation (Priority: P2)
+
+As a user exploring documentation with many cross-references, I want to hover over a wikilink and see a preview of the linked note's content so that I can decide whether to navigate without losing my current reading context.
+
+**Why this priority**: Significantly improves information browsing efficiency, but not essential for basic reading. Requires wikilink detection to be working, making it dependent on core functionality.
+
+**Independent Test**: Can be fully tested by creating notes with wikilinks, hovering over links for 500ms, and verifying preview appears with first 150 characters. Delivers context-aware navigation value independently.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am viewing a note containing a wikilink, **When** I hover my mouse over the wikilink for 500 milliseconds, **Then** a tooltip appears showing the first 150 characters of the linked note
+2. **Given** a wikilink preview tooltip is displayed, **When** I move my mouse away, **Then** the tooltip disappears
+3. **Given** a wikilink points to a non-existent note, **When** I hover over it, **Then** the tooltip shows "Note not found" or similar message
+4. **Given** I quickly move my mouse across multiple wikilinks, **When** I don't pause for 500ms on any link, **Then** no tooltips appear (prevents flickering)
+
+---
+
+### User Story 4 - Estimate Reading Time (Priority: P2)
+
+As a user planning my documentation reading sessions, I want to see an estimated reading time for each note so that I can decide whether to read now or bookmark for later.
+
+**Why this priority**: Helpful for time management but not critical for basic functionality. Very quick to implement and adds professional polish.
+
+**Independent Test**: Can be fully tested by opening notes of varying lengths and verifying reading time badge appears with accurate estimates. Delivers time-planning value independently.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am viewing a note with 600 words, **When** the note loads, **Then** I see a badge showing "~3 min read" near the note title
+2. **Given** I am viewing a note with fewer than 200 words, **When** the note loads, **Then** no reading time badge is displayed (< 1 minute threshold)
+3. **Given** I am viewing a note with 1500 words, **When** the note loads, **Then** I see "~8 min read" (1500 / 200 = 7.5, rounded up)
+
+---
+
+### User Story 5 - Navigate Long Technical Documentation (Priority: P2)
+
+As a user reading lengthy technical documentation, I want to see a table of contents with clickable headings so that I can quickly jump to specific sections without scrolling through the entire document.
+
+**Why this priority**: Very valuable for long documents but only applies to a subset of notes. More complex to implement than other features.
+
+**Independent Test**: Can be fully tested by opening a long note with H1-H3 headings, toggling the TOC panel, clicking headings to scroll, and verifying persistence. Delivers section navigation value independently.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am viewing a note with multiple headings, **When** I click the "TOC" button in the toolbar, **Then** a flyout panel appears on the right side showing all H1, H2, and H3 headings
+2. **Given** the TOC panel is open, **When** I click on a heading in the TOC, **Then** the note scrolls smoothly to that section
+3. **Given** the TOC panel is open, **When** I click the "TOC" button again or click outside the panel, **Then** the panel closes
+4. **Given** I have opened the TOC panel, **When** I close it and reload the page, **Then** the panel state (open/closed) is remembered
+5. **Given** I am viewing a note with no headings, **When** I click "TOC", **Then** the panel shows "No headings found" message
+
+---
+
+### User Story 6 - Experience Polished Interface (Priority: P3)
+
+As a user navigating between notes and views, I want to see smooth transitions and animations so that the interface feels polished and professional rather than abrupt.
+
+**Why this priority**: Nice-to-have polish that improves perceived quality but doesn't add functional value. Should be implemented last.
+
+**Independent Test**: Can be fully tested by switching between notes, toggling graph view, and selecting tree items to verify animations play. Delivers visual polish value independently.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am viewing one note, **When** I select a different note, **Then** the new note content fades in over 300 milliseconds
+2. **Given** I am in note view, **When** I toggle to graph view, **Then** the graph slides in over 250 milliseconds
+3. **Given** I click on a directory tree item, **When** the item becomes selected, **Then** it highlights with a smooth transition
+
+---
+
+### User Story 7 - Visual Click Feedback (Priority: STRETCH)
+
+As a user clicking on interactive elements, I want to see playful particle effects so that the interface feels more engaging and responsive to my actions.
+
+**Why this priority**: Stretch goal - adds delight but risks feeling gimmicky or causing performance issues. Only implement if time permits and other features are stable.
+
+**Independent Test**: Can be fully tested by clicking various UI elements (links, buttons, tree items) and verifying particle animations appear without lag. Delivers engagement value independently but has higher risk of bugs.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am using the interface, **When** I click on a wikilink, **Then** a small particle burst animation appears at the click point
+2. **Given** I am using the interface, **When** I click on a tree item, **Then** particle effects appear without causing UI lag or freezing
+3. **Given** particle effects are enabled, **When** I perform rapid clicks, **Then** the system gracefully handles multiple simultaneous animations
+
+---
+
+### Edge Cases
+
+- What happens when a user sets font size to large and then views a note with very long lines? (Text should wrap properly, not overflow)
+- How does the TOC handle notes with duplicate heading text? (Should still scroll to correct position based on document order)
+- What happens when a wikilink preview is requested for a very large note? (Show only first 150 characters, no performance impact)
+- How does "Expand All" perform with 100+ folders? (Should complete in under 2 seconds, show loading state if needed)
+- What happens when a user hovers on a wikilink but the note hasn't been indexed yet? (Show "Loading..." then content or error)
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: System MUST provide three font size options: Small (14px), Medium (16px), and Large (18px) for note body text
+- **FR-002**: System MUST persist user's font size preference across browser sessions using localStorage
+- **FR-003**: System MUST display "Expand All" and "Collapse All" buttons above the directory tree
+- **FR-004**: "Expand All" button MUST open all folder nodes in the directory tree regardless of current state
+- **FR-005**: "Collapse All" button MUST close all folder nodes in the directory tree
+- **FR-006**: System MUST display a preview tooltip when user hovers over a wikilink for 500 milliseconds
+- **FR-007**: Wikilink preview tooltip MUST show the first 150 characters of the target note's body content
+- **FR-008**: System MUST calculate reading time as word count divided by 200 words per minute
+- **FR-009**: System MUST display reading time badge only for notes estimated to take 1 minute or longer
+- **FR-010**: System MUST generate a table of contents from H1, H2, and H3 headings in the current note
+- **FR-011**: TOC panel MUST be toggleable via a "TOC" button in the note viewer toolbar
+- **FR-012**: Clicking a TOC heading MUST smoothly scroll the note to that section
+- **FR-013**: TOC panel state (open/closed) MUST persist across page reloads using localStorage
+- **FR-014**: Note content transitions MUST use fade-in animation (300ms duration)
+- **FR-015**: Graph view transitions MUST use slide-in animation (250ms duration)
+- **FR-016**: Font size changes MUST only affect note body text, not UI chrome (sidebar, toolbar, headers)
+- **FR-017**: Wikilink preview MUST not appear if mouse moves away before 500ms delay
+- **FR-018** (STRETCH): System MAY display particle burst effects on click events for wikilinks, buttons, and tree items
+
+### Key Entities
+
+- **Font Size Preference**: User's selected text size (small/medium/large), persisted in localStorage
+- **TOC Panel State**: Boolean indicating whether TOC panel is open or closed, persisted in localStorage
+- **TOC Heading**: Extracted heading from markdown with text, level (H1/H2/H3), and scroll position
+- **Reading Time Estimate**: Calculated value in minutes based on note word count
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: Users can adjust font size and see the change applied instantly (< 100ms)
+- **SC-002**: Font size preference persists correctly across 100% of browser sessions
+- **SC-003**: "Expand All" completes in under 2 seconds for vaults with up to 100 folders
+- **SC-004**: Wikilink preview tooltips appear within 100ms after the 500ms hover delay
+- **SC-005**: Reading time estimates are accurate within ±20% of actual reading time for 90% of notes
+- **SC-006**: TOC generation completes in under 500ms for notes with up to 50 headings
+- **SC-007**: All transitions and animations complete without visual jank or frame drops (60 FPS)
+- **SC-008**: TOC panel state persists correctly across 100% of page reloads
+- **SC-009**: Users can navigate to any section in a 20-heading document in under 3 seconds using TOC
+- **SC-010**: Rapid hovering over multiple wikilinks does not cause tooltip flickering or performance degradation
+
+## Assumptions
+
+- Users primarily read documentation rather than edit it, so reading comfort features are valuable
+- Most vaults contain between 10-100 notes with 2-4 levels of folder nesting
+- Average reading speed is 200 words per minute (industry standard)
+- Users are accessing the application via modern browsers with localStorage support
+- Notes use standard markdown heading syntax (#, ##, ###)
+- Font size preference applies globally to all notes, not per-note
+- Wikilink previews fetching note content from existing API endpoints is acceptable (no new backend changes required)
+- Particle effects (stretch goal) would use CSS-based animations or lightweight canvas library
+- TOC panel appears on right side of note viewer, overlaying content on smaller screens
+- Smooth transitions use CSS transitions or React spring animations (existing capabilities)

specs/006-ui-polish/tasks.md

@@ -0,0 +1,392 @@
+---
+
+description: "Implementation tasks for UI Polish Pack feature"
+---
+
+# Tasks: UI Polish Pack
+
+**Input**: Design documents from `/specs/006-ui-polish/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, quickstart.md
+
+**Tests**: No automated tests - manual verification per quickstart.md checklist
+
+**Organization**: Tasks are grouped by user story (P1 → P2 → P3 → STRETCH) to enable independent implementation and testing of each polish feature.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Web app**: `frontend/src/` for all React/TypeScript code
+- No backend changes required for this feature
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Install dependencies and prepare development environment
+
+- [ ] T001 Install shadcn/ui HoverCard component via `npx shadcn@latest add hover-card` in frontend/
+- [ ] T002 [P] Verify tailwindcss-animate is installed in frontend/package.json (existing dependency)
+- [ ] T003 [P] Verify development server runs successfully via `npm run dev` in frontend/
+
+**Checkpoint**: Dependencies ready, dev server running
+
+---
+
+## Phase 2: Foundational (No blocking prerequisites)
+
+**Purpose**: This feature has NO foundational blocking tasks - all user stories are independent frontend polish features
+
+**⚠️ NOTE**: User story implementation can begin immediately after Phase 1
+
+**Checkpoint**: Foundation ready - proceed directly to user stories
+
+---
+
+## Phase 3: User Story 1 - Adjust Reading Comfort (Priority: P1) 🎯 MVP
+
+**Goal**: Allow users to adjust font size (small/medium/large) with localStorage persistence for comfortable reading
+
+**Independent Test**: Open any note, click A-/A/A+ buttons, verify text resizes instantly and persists after page reload
+
+### Implementation for User Story 1
+
+- [ ] T004 [P] [US1] Add CSS custom property `--content-font-size: 1rem;` to `:root` in frontend/src/index.css
+- [ ] T005 [P] [US1] Apply `font-size: var(--content-font-size)` to `.prose` class in frontend/src/index.css
+- [ ] T006 [US1] Create useFontSize hook in frontend/src/hooks/useFontSize.ts with localStorage persistence
+- [ ] T007 [US1] Add font size state management to MainApp component in frontend/src/pages/MainApp.tsx
+- [ ] T008 [US1] Pass fontSize props to NoteViewer in frontend/src/pages/MainApp.tsx
+- [ ] T009 [US1] Add font size buttons (A-, A, A+) to NoteViewer toolbar in frontend/src/components/NoteViewer.tsx
+- [ ] T010 [US1] Update CSS variable dynamically when font size changes in frontend/src/hooks/useFontSize.ts
+- [ ] T011 [US1] Verify font size only affects .prose content, not UI chrome (manual test)
+
+**Checkpoint**: Font size adjuster complete - text resizes with buttons, preference persists, UI chrome unaffected
+
+---
+
+## Phase 4: User Story 2 - Navigate Large Documentation Structures (Priority: P1)
+
+**Goal**: Provide "Expand All" and "Collapse All" buttons for directory tree navigation in large vaults
+
+**Independent Test**: Create vault with 3+ levels of nested folders, click Expand All to see entire tree, click Collapse All to hide all folders
+
+### Implementation for User Story 2
+
+- [ ] T012 [P] [US2] Add expandAll state to DirectoryTree component in frontend/src/components/DirectoryTree.tsx
+- [ ] T013 [P] [US2] Add collapseAll state to DirectoryTree component in frontend/src/components/DirectoryTree.tsx
+- [ ] T014 [US2] Add forceExpandState prop to TreeNodeItem recursive component in frontend/src/components/DirectoryTree.tsx
+- [ ] T015 [US2] Implement expand/collapse state propagation logic in frontend/src/components/DirectoryTree.tsx
+- [ ] T016 [US2] Add "Expand All" button above directory tree in frontend/src/components/DirectoryTree.tsx
+- [ ] T017 [US2] Add "Collapse All" button above directory tree in frontend/src/components/DirectoryTree.tsx
+- [ ] T018 [US2] Verify expand all completes in <2s for 100+ folders (performance test)
+
+**Checkpoint**: Expand/collapse all buttons work, all folders respond to state changes, performance acceptable
+
+---
+
+## Phase 5: User Story 3 - Preview Note Content Without Navigation (Priority: P2)
+
+**Goal**: Show HoverCard preview with first 150 characters of linked note when hovering over wikilink for 500ms
+
+**Independent Test**: Create notes with wikilinks, hover over links for 500ms, verify preview appears with first 150 characters
+
+### Implementation for User Story 3
+
+- [ ] T019 [P] [US3] Create wikilink preview cache state (Map<string, string>) in markdown.tsx or NoteViewer component
+- [ ] T020 [P] [US3] Import HoverCard component in frontend/src/lib/markdown.tsx
+- [ ] T021 [US3] Wrap wikilink spans with HoverCard in wikilink renderer in frontend/src/lib/markdown.tsx
+- [ ] T022 [US3] Set HoverCard openDelay={500} and closeDelay={100} in frontend/src/lib/markdown.tsx
+- [ ] T023 [US3] Implement preview fetch logic using existing GET /api/notes/{path} endpoint
+- [ ] T024 [US3] Extract first 150 characters from note body for preview display
+- [ ] T025 [US3] Add loading skeleton during preview fetch in HoverCard content
+- [ ] T026 [US3] Handle broken wikilinks (show "Note not found" message)
+- [ ] T027 [US3] Verify no tooltips appear when mouse moves away before 500ms (flicker prevention test)
+- [ ] T028 [US3] Verify preview cache works (second hover on same link is instant)
+
+**Checkpoint**: Wikilink previews appear after 500ms hover, show correct content, handle errors gracefully
+
+---
+
+## Phase 6: User Story 4 - Estimate Reading Time (Priority: P2)
+
+**Goal**: Display reading time badge ("X min read") for notes estimated to take 1+ minutes at 200 WPM
+
+**Independent Test**: Open notes of varying lengths, verify reading time badge appears with accurate estimates
+
+### Implementation for User Story 4
+
+- [ ] T029 [P] [US4] Import markdownToPlainText utility in frontend/src/components/NoteViewer.tsx
+- [ ] T030 [P] [US4] Import Badge component from shadcn/ui in frontend/src/components/NoteViewer.tsx
+- [ ] T031 [US4] Create useMemo hook to calculate reading time from note.body in frontend/src/components/NoteViewer.tsx
+- [ ] T032 [US4] Extract word count: plainText.trim().split(/\\s+/).length in reading time calculation
+- [ ] T033 [US4] Calculate minutes: Math.ceil(wordCount / 200) in reading time calculation
+- [ ] T034 [US4] Return null if <1 minute (200 words threshold) in reading time calculation
+- [ ] T035 [US4] Render Badge with "X min read" near note title in frontend/src/components/NoteViewer.tsx
+- [ ] T036 [US4] Verify badge appears only for notes >200 words (manual test)
+
+**Checkpoint**: Reading time badge displays for long notes, hidden for short notes, estimates accurate within ±20%
+
+---
+
+## Phase 7: User Story 5 - Navigate Long Technical Documentation (Priority: P2)
+
+**Goal**: Provide table of contents flyout panel with clickable headings (H1-H3) for long notes
+
+**Independent Test**: Open long note with H1-H3 headings, toggle TOC panel, click headings to scroll, verify persistence
+
+### Implementation for User Story 5
+
+- [ ] T037 [P] [US5] Create useTableOfContents hook in frontend/src/hooks/useTableOfContents.ts
+- [ ] T038 [P] [US5] Create TableOfContents component in frontend/src/components/TableOfContents.tsx
+- [ ] T039 [US5] Add heading ID generation to h1/h2/h3 renderers in frontend/src/lib/markdown.tsx
+- [ ] T040 [US5] Implement slugify function: text.toLowerCase().replace(/\\s+/g, '-').replace(/[^\\w-]/g, '') in markdown.tsx
+- [ ] T041 [US5] Extract headings { id, text, level }[] using useRef during render in useTableOfContents hook
+- [ ] T042 [US5] Add TOC panel state (isOpen) to NoteViewer in frontend/src/components/NoteViewer.tsx
+- [ ] T043 [US5] Persist TOC panel state to localStorage key 'toc-panel-open' in useTableOfContents hook
+- [ ] T044 [US5] Add "TOC" button to NoteViewer toolbar in frontend/src/components/NoteViewer.tsx
+- [ ] T045 [US5] Render TableOfContents component as ResizablePanel (right sidebar) in frontend/src/components/NoteViewer.tsx
+- [ ] T046 [US5] Implement scrollToHeading function with smooth scroll behavior in useTableOfContents hook
+- [ ] T047 [US5] Respect prefers-reduced-motion media query in scroll behavior in useTableOfContents hook
+- [ ] T048 [US5] Add hierarchical indentation by heading level in TableOfContents component
+- [ ] T049 [US5] Show "No headings found" message when headings array is empty in TableOfContents component
+- [ ] T050 [US5] Handle duplicate heading text by appending -2, -3 to IDs in slugify function
+- [ ] T051 [US5] Verify TOC panel state persists after reload (manual test)
+- [ ] T052 [US5] Verify TOC generation completes in <500ms for 50 headings (performance test)
+
+**Checkpoint**: TOC panel toggles, headings are clickable, smooth scrolling works, state persists, performance acceptable
+
+---
+
+## Phase 8: User Story 6 - Experience Polished Interface (Priority: P3)
+
+**Goal**: Add smooth CSS transitions/animations to note switching, graph toggle, and tree selection
+
+**Independent Test**: Switch between notes, toggle graph view, select tree items to verify animations play smoothly at 60 FPS
+
+### Implementation for User Story 6
+
+- [ ] T053 [P] [US6] Extend Tailwind config with custom transition utilities in frontend/tailwind.config.js
+- [ ] T054 [P] [US6] Add fade-in transition keyframe (300ms) in frontend/tailwind.config.js
+- [ ] T055 [P] [US6] Add slide-in transition keyframe (250ms) in frontend/tailwind.config.js
+- [ ] T056 [US6] Apply fade-in transition to note content container in frontend/src/components/NoteViewer.tsx
+- [ ] T057 [US6] Apply slide-in transition to graph view toggle in frontend/src/pages/MainApp.tsx
+- [ ] T058 [US6] Apply smooth transition to directory tree item selection in frontend/src/components/DirectoryTree.tsx
+- [ ] T059 [US6] Add prefers-reduced-motion media query support to all transitions
+- [ ] T060 [US6] Verify animations maintain 60 FPS (Chrome DevTools Performance tab test)
+- [ ] T061 [US6] Verify animations only use transform/opacity (no layout thrashing)
+
+**Checkpoint**: All transitions smooth, 60 FPS maintained, reduced motion respected
+
+---
+
+## Phase 9: User Story 7 - Visual Click Feedback (Priority: STRETCH)
+
+**Goal**: Add playful particle effects on click events for wikilinks, buttons, and tree items
+
+**Independent Test**: Click various UI elements, verify particle animations appear without lag
+
+**⚠️ STRETCH**: Only implement if time permits and P1/P2/P3 features are stable
+
+### Implementation for User Story 7
+
+- [ ] T062 [P] [US7] Decide implementation approach: CSS-only vs shadcn particles component
+- [ ] T063 [P] [US7] If CSS-only: Create particle animation keyframes in frontend/src/index.css
+- [ ] T064 [P] [US7] If shadcn: Install particles component via `npx shadcn@latest add particles`
+- [ ] T065 [US7] Add particle effect trigger to wikilink click handler in frontend/src/lib/markdown.tsx
+- [ ] T066 [US7] Add particle effect trigger to tree item click handler in frontend/src/components/DirectoryTree.tsx
+- [ ] T067 [US7] Add particle effect trigger to button click handlers in NoteViewer/MainApp
+- [ ] T068 [US7] Limit particle count to 50 max for performance
+- [ ] T069 [US7] Disable particles on mobile devices (media query)
+- [ ] T070 [US7] Respect prefers-reduced-motion (disable particles if set)
+- [ ] T071 [US7] Verify no lag or frame drops during rapid clicking (stress test)
+- [ ] T072 [US7] Verify particles use transform-only animations (no layout thrashing)
+
+**Checkpoint**: Particle effects enhance engagement without performance degradation
+
+---
+
+## Phase 10: Polish & Cross-Cutting Concerns
+
+**Purpose**: Final verification and cross-story polish
+
+- [ ] T073 [P] Run complete quickstart.md testing checklist for all implemented stories
+- [ ] T074 [P] Test font size adjuster checklist (7 items) from quickstart.md
+- [ ] T075 [P] Test expand/collapse all checklist (6 items) from quickstart.md
+- [ ] T076 [P] Test wikilink preview tooltips checklist (7 items) from quickstart.md
+- [ ] T077 [P] Test reading time estimator checklist (5 items) from quickstart.md
+- [ ] T078 [P] Test table of contents checklist (10 items) from quickstart.md
+- [ ] T079 [P] Test smooth transitions checklist (5 items) from quickstart.md
+- [ ] T080 [P] Test particle effects checklist (5 items) from quickstart.md (if implemented)
+- [ ] T081 [P] Browser compatibility testing: Chrome, Firefox, Safari, Edge
+- [ ] T082 [P] Mobile responsiveness testing: iOS Safari, Android Chrome
+- [ ] T083 [P] Accessibility verification: keyboard navigation, ARIA labels, WCAG 2.2 Level AA
+- [ ] T084 [P] Performance profiling: Chrome DevTools Performance tab
+- [ ] T085 [P] Memory profiling: Check for leaks in preview cache and event listeners
+- [ ] T086 Build production bundle via `npm run build` in frontend/
+- [ ] T087 Preview production build via `npm run preview` and re-test all features
+- [ ] T088 Verify bundle size is reasonable (~400-500KB gzipped)
+- [ ] T089 Update CLAUDE.md if new patterns established (already done in planning phase)
+- [ ] T090 Commit final changes with message per git commit guidelines
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: N/A - no blocking foundational tasks for this feature
+- **User Stories (Phase 3-9)**: Each user story is independent and can start after Phase 1
+  - US1 (Font Size): Can start immediately after Phase 1
+  - US2 (Expand/Collapse): Can start immediately after Phase 1
+  - US3 (Wikilink Preview): Can start immediately after Phase 1
+  - US4 (Reading Time): Can start immediately after Phase 1
+  - US5 (Table of Contents): Can start immediately after Phase 1
+  - US6 (Transitions): Can start immediately after Phase 1
+  - US7 (Particles): STRETCH - only if time permits after P1/P2/P3
+- **Polish (Phase 10)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: INDEPENDENT - No dependencies on other stories
+- **User Story 2 (P1)**: INDEPENDENT - No dependencies on other stories
+- **User Story 3 (P2)**: INDEPENDENT - No dependencies on other stories
+- **User Story 4 (P2)**: INDEPENDENT - No dependencies on other stories
+- **User Story 5 (P2)**: INDEPENDENT - No dependencies on other stories
+- **User Story 6 (P3)**: INDEPENDENT - No dependencies on other stories (applies transitions to existing UI)
+- **User Story 7 (STRETCH)**: INDEPENDENT - No dependencies on other stories
+
+### Within Each User Story
+
+- Tasks within a story may have sequential dependencies (e.g., create hook before using it)
+- Tasks marked [P] can run in parallel (different files)
+- Complete story checkpoint before moving to next priority
+
+### Parallel Opportunities
+
+- **Phase 1**: T002 and T003 can run in parallel with T001
+- **User Stories**: All 7 user stories can be implemented in parallel by different developers (after Phase 1)
+- **Within Stories**: Tasks marked [P] can run in parallel
+  - US1: T004 and T005 (CSS changes) can run in parallel
+  - US2: T012 and T013 (state additions) can run in parallel
+  - US3: T019 and T020 (imports) can run in parallel
+  - US4: T029 and T030 (imports) can run in parallel
+  - US5: T037 and T038 (hook + component scaffolding) can run in parallel
+  - US6: T053, T054, T055 (Tailwind config) can run in parallel
+  - US7: T062, T063, T064 (approach decision) can run in parallel
+- **Polish (Phase 10)**: T073-T085 (all testing tasks) can run in parallel
+
+---
+
+## Parallel Example: User Story 1 (Font Size)
+
+```bash
+# Launch CSS changes in parallel:
+Task T004: "Add CSS custom property --content-font-size to :root in frontend/src/index.css"
+Task T005: "Apply font-size: var(--content-font-size) to .prose class in frontend/src/index.css"
+
+# Then create hook (sequential - needed before component integration):
+Task T006: "Create useFontSize hook in frontend/src/hooks/useFontSize.ts"
+
+# Then integrate into components (sequential - depends on hook):
+Task T007: "Add font size state management to MainApp"
+Task T008: "Pass fontSize props to NoteViewer"
+Task T009: "Add font size buttons to NoteViewer toolbar"
+```
+
+---
+
+## Parallel Example: User Story 5 (Table of Contents)
+
+```bash
+# Launch hook and component scaffolding in parallel:
+Task T037: "Create useTableOfContents hook in frontend/src/hooks/useTableOfContents.ts"
+Task T038: "Create TableOfContents component in frontend/src/components/TableOfContents.tsx"
+
+# Then implement markdown heading extraction (sequential):
+Task T039: "Add heading ID generation to h1/h2/h3 renderers"
+Task T040: "Implement slugify function"
+Task T041: "Extract headings using useRef during render"
+
+# Then integrate (sequential - depends on hook + component):
+Task T042-T052: "Integrate TOC panel into NoteViewer with state/persistence/scrolling"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Stories 1 & 2 Only - Both P1)
+
+1. Complete Phase 1: Setup (~5 min)
+2. Complete Phase 3: User Story 1 - Font Size (~15 min)
+3. **STOP and VALIDATE**: Test font size independently per quickstart.md
+4. Complete Phase 4: User Story 2 - Expand/Collapse All (~20 min)
+5. **STOP and VALIDATE**: Test expand/collapse independently per quickstart.md
+6. Deploy/demo if ready (MVP with 2 core features)
+
+**Total MVP Time**: ~40 minutes for P1 features only
+
+### Incremental Delivery (Priority Order)
+
+1. **Setup (Phase 1)** → Dependencies ready (~5 min)
+2. **P1 Features (Phases 3-4)** → Font Size + Expand/Collapse → Test → Deploy (~40 min total)
+3. **P2 Features (Phases 5-7)** → Wikilink Preview + Reading Time + TOC → Test → Deploy (~80 min total)
+4. **P3 Features (Phase 8)** → Smooth Transitions → Test → Deploy (~10 min)
+5. **STRETCH (Phase 9)** → Particle Effects → Test → Deploy (~45 min) - OPTIONAL
+6. **Polish (Phase 10)** → Comprehensive testing + build → Deploy (~30 min)
+
+**Total Time Estimate**:
+- P1 only: ~40 min (MVP)
+- P1 + P2: ~120 min (recommended hackathon scope)
+- P1 + P2 + P3: ~130 min (full polish)
+- All features (including STRETCH): ~175 min (if time permits)
+
+### Parallel Team Strategy
+
+With multiple developers (after Phase 1 setup):
+
+**Option A: Priority-based (Recommended)**
+1. Developer A: User Story 1 (Font Size) - P1
+2. Developer B: User Story 2 (Expand/Collapse) - P1
+3. After P1 complete and tested:
+   - Developer A: User Story 3 (Wikilink Preview) - P2
+   - Developer B: User Story 4 (Reading Time) - P2
+   - Developer C: User Story 5 (Table of Contents) - P2
+
+**Option B: Full parallel**
+1. Developer A: User Stories 1 & 4 (Font Size + Reading Time)
+2. Developer B: User Stories 2 & 6 (Expand/Collapse + Transitions)
+3. Developer C: User Stories 3 & 5 (Wikilink Preview + TOC)
+4. Developer D: User Story 7 (Particles - STRETCH)
+
+**Option C: Serial (Single Developer)**
+1. Follow priority order: US1 → US2 → US4 → US3 → US5 → US6 → US7 (STRETCH)
+2. Stop after any checkpoint to demo/deploy incremental value
+
+---
+
+## Notes
+
+- **[P] tasks**: Different files, no dependencies - safe to parallelize
+- **[Story] label**: Maps task to specific user story for traceability
+- **No tests**: Manual verification only per quickstart.md checklist
+- **Independent stories**: Each story can be completed and tested without others
+- **Frontend-only**: No backend changes required
+- **Existing patterns**: Leverages CSS variables, React hooks, shadcn/ui, tailwindcss-animate
+- **New dependencies**: Only @radix-ui/react-hover-card (installed in Phase 1)
+- **Performance targets**: All documented in success criteria (SC-001 through SC-010)
+- **Accessibility**: WCAG 2.2 Level AA compliance required
+- **Commit strategy**: Commit after each completed user story checkpoint
+- **Deployment**: Can deploy after any user story completion (incremental value)
+- **STRETCH goal**: User Story 7 (Particles) only if P1/P2/P3 stable and time permits
+
+---
+
+**Recommended Hackathon Scope**: P1 + P2 features (User Stories 1-5) = ~120 min implementation + 30 min testing/polish = **2.5 hours total**
+
+This delivers maximum polish impact with minimal risk. P3 (Transitions) and STRETCH (Particles) can be added if time remains.