---
stepsCompleted: [1, 2, 3, 4, 5, 6]
workflowType: 'create-epics-and-stories'
status: 'complete'
createdAt: '2026-01-15'
completedAt: '2026-01-17'
totalEpics: 17
totalStories: ~155
totalFRs: 54
totalNFRs: 47
inputDocuments:
  - _bmad-output/planning-artifacts/prd-phase1-mvp-ai.md
  - _bmad-output/planning-artifacts/architecture.md
  - _bmad-output/planning-artifacts/ux-design-specification.md
  - _bmad-output/planning-artifacts/PRD-KEEP-REDESIGN.md
  - _bmad-output/planning-artifacts/DESIGN-WIREFRAMES.md
note: MISE À JOUR 2026-01-17 - CHOIX DE RAMEZ : OPTION 1 VALIDÉE
note2: LES ÉPICS 1-12 SONT CONSERVÉS TELS QUELS (78 User Stories existantes) - PAS DE MODIFICATION
note3: LES ÉPICS 13-17 SONT NOUVEAUX (77 User Stories ajoutées)
note4: TOTAL = 17 ÉPICS avec 155 User Stories (78 conservés + 77 nouvelles)
note5: RÉPONSES DE RAMEZ : Q1=OUI (conserver), Q2=OUI (garder dans backlog), Q3=NON (pas de méta-données)
---

# Keep - Epic Breakdown

## Overview

This document provides the complete epic and story breakdown for Keep, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.

## Requirements Inventory

### Functional Requirements

FR1: Users can receive AI-generated title suggestions when writing notes without titles
FR2: Users can view multiple title suggestion options before selecting one
FR3: Users can apply AI-generated titles to their notes with a single action
FR4: Users can defer title suggestions to view later
FR5: Users can dismiss title suggestions for specific notes permanently
FR6: Users can request AI-powered reformulation of selected paragraph content
FR7: Users can select different reformulation approaches (clarify, shorten, improve style)
FR8: Users can replace original content with AI-reformulated versions
FR9: Users can cancel reformulation actions and retain original content
FR10: Users can provide positive or negative feedback on AI-generated content
FR11: Users can search notes using keyword queries that match exact text
FR12: Users can search notes using natural language queries that match semantic meaning
FR13: Users can view combined search results from both keyword and semantic matching
FR14: Users can see visual indicators distinguishing exact matches from semantic matches
FR15: Users can receive proactive insights about connections between related notes
FR16: Users can view the specific content and context of suggested note connections
FR17: Users can link related notes together when accepting connection suggestions
FR18: Users can dismiss proactive connection insights
FR19: Users can provide feedback on the relevance of suggested note connections
FR20: Users can access AI settings to configure individual feature availability
FR21: Users can enable or disable title suggestions independently
FR22: Users can enable or disable semantic search independently
FR23: Users can enable or disable paragraph reformulation independently
FR24: Users can enable or disable proactive connection insights independently
FR25: Users can adjust the frequency limit for proactive connection insights
FR26: Users can customize AI trigger thresholds (e.g., word count for title suggestions)
FR27: Users can set time period constraints for proactive connection analysis
FR28: Users can temporarily disable all proactive AI features during focused work sessions
FR29: Users can re-enable disabled AI features through settings interface
FR30: Users can select between local AI processing (Ollama) and cloud AI processing (OpenAI)
FR31: Users can verify that local AI processing does not send data external to their device
FR32: Users can view connection status indicators for AI providers
FR33: Users can switch between AI providers without losing functionality
FR34: The system can automatically fallback to alternative AI providers if primary provider fails
FR35: Users can configure API keys for cloud AI providers
FR36: Users can remove stored API credentials from the system
FR37: The system can detect and support multiple languages in user-generated content
FR38: The system can process AI requests using user's content language while maintaining system prompts in English
FR39: Administrators can configure default AI provider settings for all users
FR40: Administrators can set rate limits on AI usage per user
FR41: Administrators can override individual user AI settings
FR42: Administrators can monitor real-time AI usage metrics across the system
FR43: Administrators can view AI processing costs and consumption statistics
FR44: Administrators can adjust AI model parameters (temperature, max tokens, etc.)
FR45: Administrators can configure team-wide AI feature availability
FR46: The system can encrypt and securely store AI provider API keys
FR47: Users can access all AI features using keyboard navigation without mouse input
FR48: Users can receive screen reader announcements for AI-generated content and suggestions
FR49: Users can dismiss AI notifications and suggestions using keyboard shortcuts
FR50: Users can view and interact with AI features on mobile devices (320px-639px)
FR51: Users can view and interact with AI features on tablet devices (640px-1023px)
FR52: Users can view and interact with AI features on desktop devices (1024px+)
FR53: Users can perceive visual focus indicators on all interactive AI elements
FR54: Users can access AI features with touch targets meeting minimum size requirements (44x44px on mobile)

### NonFunctional Requirements

NFR-PERF-001: Title suggestions generate within 2 seconds of trigger detection
NFR-PERF-002: Semantic search results return within 300 milliseconds for databases up to 1,000 notes
NFR-PERF-003: Memory Echo background analysis completes with less than 100 milliseconds of UI thread blocking
NFR-PERF-004: Paragraph reformulation completes within 5 seconds for content up to 500 words
NFR-PERF-005: Initial page load achieves First Contentful Paint (FCP) in under 3 seconds on 4G connections
NFR-PERF-006: Application reaches Time to Interactive (TTI) within 5 seconds on modern browsers
NFR-PERF-007: JavaScript bundle remains under 200KB gzipped (excluding AI provider libraries)
NFR-PERF-008: AI features load on-demand without affecting initial application bundle size
NFR-PERF-009: System supports 50 concurrent users with less than 10% performance degradation
NFR-PERF-010: Search response time remains under 500ms with 10,000 notes in database
NFR-SEC-001: All user notes are encrypted at rest in the database
NFR-SEC-002: All data transmitted between client and server uses HTTPS/TLS 1.3+
NFR-SEC-003: User passwords are hashed using bcrypt with minimum 12 salt rounds
NFR-SEC-004: AI provider API keys are encrypted when stored in database
NFR-SEC-005: Local AI processing (Ollama) sends zero data to external services
NFR-SEC-006: Users can verify local processing mode through network inspection tools
NFR-SEC-007: User content language detection and processing occurs server-side without exposing raw content to external AI providers when using local mode
NFR-SEC-008: System does not log or store user note content beyond database persistence
NFR-SEC-009: User sessions expire after 30 days of inactivity
NFR-SEC-010: Password reset tokens expire within 1 hour of generation
NFR-SEC-011: Administrator access requires explicit role assignment (default role is USER)
NFR-SEC-012: Users can only access their own notes, labels, and AI settings unless explicitly granted admin privileges
NFR-SEC-013: All API routes validate user authentication before processing requests
NFR-SEC-014: Rate limiting prevents abuse of AI endpoints (maximum 100 requests per minute per user)
NFR-A11Y-001: All AI features are fully operable using keyboard-only navigation
NFR-A11Y-002: Screen readers announce AI-generated content and suggestions with descriptive text
NFR-A11Y-003: All interactive AI elements have visible focus indicators with minimum 3:1 contrast ratio
NFR-A11Y-004: Color alone is not used to convey information; visual indicators include text labels or icons
NFR-A11Y-005: All interactive AI elements on mobile devices meet minimum tap target size of 44×44 pixels
NFR-A11Y-006: Touch targets have minimum 8 pixels spacing between adjacent interactive elements
NFR-A11Y-007: AI features function correctly on mobile devices (320px-639px viewport width)
NFR-A11Y-008: AI features function correctly on tablet devices (640px-1023px viewport width)
NFR-A11Y-009: AI features function correctly on desktop devices (1024px+ viewport width)
NFR-A11Y-010: AI toast notifications use `role="status"` (not `role="alert"`) to avoid interrupting screen reader navigation
NFR-A11Y-011: Notifications can be dismissed using keyboard ESC key
NFR-REL-001: Application achieves 99% uptime during business hours (9 AM - 6 PM user local time)
NFR-REL-002: Graceful degradation occurs if AI providers are unavailable (core note-taking features remain functional)
NFR-REL-003: AI feature failures display user-friendly error messages without technical jargon
NFR-REL-004: Failed AI requests automatically retry with exponential backoff (maximum 3 attempts)
NFR-REL-005: System provides fallback to alternative AI provider if primary provider fails
NFR-REL-006: All user actions maintain ACID properties (Atomic, Consistent, Isolated, Durable)
NFR-REL-007: Vector embeddings are cached after generation to prevent redundant processing
NFR-REL-008: Memory Echo analysis runs asynchronously without blocking user interactions
NFR-REL-009: Background jobs log failures for administrator review without exposing errors to end users
NFR-INT-001: System supports OpenAI API for cloud AI processing
NFR-INT-002: System supports Ollama API for local AI processing
NFR-INT-003: Factory pattern allows adding new AI providers without modifying existing code
NFR-INT-004: Users can switch between AI providers without losing data or functionality
NFR-INT-005: System automatically detects available AI providers during startup
NFR-INT-006: Provider connection status indicators display current operational state
NFR-INT-007: System maintains compatibility with OpenAI API versions through abstraction layer
NFR-INT-008: Ollama integration supports all models compatible with `/api/tags` and `/api/embeddings` endpoints
NFR-INT-009: New AI models can be added through configuration without code changes for supported providers
NFR-INT-010: Custom OpenAI-compatible endpoints can be configured through settings
NFR-SCA-001: System supports 50-200 concurrent users with acceptable performance
NFR-SCA-002: Database performs acceptably with up to 10,000 notes per user
NFR-SCA-003: Embedding generation throughput supports 100 notes per minute per user
NFR-SCA-004: SQLite database size remains under 2GB for 100,000 notes with embeddings
NFR-SCA-005: Memory consumption per user session remains under 100MB
NFR-SCA-006: Architecture supports migration to PostgreSQL for Phase 2 if needed for larger scale

### Additional Requirements

**From Architecture Document:**

- Database Schema Extensions: Extend existing Note model with AI-related fields (autoGenerated, aiProvider, aiConfidence, language, languageConfidence, lastAiAnalysis) without breaking changes
- New Database Models: Create AiFeedback, MemoryEchoInsight, and UserAISettings tables with proper relations and indexes
- Memory Echo Implementation: Server Action + Queue in DB pattern with background processing (< 100ms UI freeze)
- Language Detection Strategy: Hybrid approach using TinyLD library (TypeScript native, 62 languages including Persian) for short notes, AI detection for long notes (≥50 words)
- AI Settings Storage: Dedicated UserAISettings table with typed fields for analytics and type safety
- Factory Pattern Extension: Extend existing AI provider factory pattern (lib/ai/factory.ts) for new AI features
- API Routes Namespace: All new AI endpoints in /api/ai/* namespace following existing patterns
- Response Format: Maintain {success: true|false, data: any, error: string} format across all API routes
- Zero Breaking Changes: All existing features must continue to function without modification
- Component Architecture: New AI components in components/ai/ directory following existing patterns
- Service Layer: New AI services in lib/ai/services/ directory with consistent error handling
- Authentication: All server actions require auth() check using existing NextAuth session
- Prisma Migrations: Create migrations for schema extensions (not rewrites)
- Background Processing: Memory Echo analysis runs asynchronously without blocking UI
- Multi-Provider Support: Extend existing factory pattern to support all new AI features with OpenAI and Ollama

**From UX Design Document:**

- Contextual Smart Assistance Pattern: AI features appear only when relevant (e.g., title suggestions after 50+ words without title)
- Toast Notification Pattern: Non-intrusive toast notifications for AI feature discovery ("I have 3 title ideas for your note, view them?")
- Memory Echo "Aha!" Moment: Proactive notification pattern with max 1 insight/day (configurable 0-3), displaying 2 connected notes side-by-side
- Hybrid Search Badges: Visual indicators ("Exact Match" | "Semantic Match") to distinguish keyword vs semantic results
- Granular AI Settings UI: ON/OFF checkboxes for each AI feature, slider for Memory Echo frequency (0-3/day)
- Privacy-First Communication: Connection status indicators showing local (Ollama) vs cloud (OpenAI) processing
- Feedback Learning UI: 👍👎 buttons for AI-generated content with optional "Why is this wrong?" modal
- Responsive Design: Mobile-first approach with touch targets ≥44x44px, proper spacing, and responsive layouts for mobile (320px-639px), tablet (640px-1023px), and desktop (1024px+)
- Accessibility: WCAG 2.1 Level AA compliance with keyboard navigation, screen reader support, focus indicators, and proper ARIA roles
- Zero-Friction Philosophy: "Suggest and facilitate, never impose" - features discovered naturally, not via tutorial
- Single-Interaction Rule: Only one AI interaction at a time (Memory Echo takes priority over title suggestions if both pending)
- Focus Mode Toggle: User can temporarily disable all proactive AI features during focused work sessions
- Visual Design: Purple (#8B5CF6) as primary AI color, semantic badges with blue gradient, consistent spacing using Tailwind 4px base unit
- Animation: Subtle fade-in and scale-up animations for AI notifications and suggestions
- Error Recovery: User-friendly error messages, retry mechanisms, and graceful degradation if AI providers unavailable

### FR Coverage Map

FR1: Epic 1 - Users can receive AI-generated title suggestions when writing notes without titles
FR2: Epic 1 - Users can view multiple title suggestion options before selecting one
FR3: Epic 1 - Users can apply AI-generated titles to their notes with a single action
FR4: Epic 1 - Users can defer title suggestions to view later
FR5: Epic 1 - Users can dismiss title suggestions for specific notes permanently
FR6: Epic 4 - Users can request AI-powered reformulation of selected paragraph content
FR7: Epic 4 - Users can select different reformulation approaches (clarify, shorten, improve style)
FR8: Epic 4 - Users can replace original content with AI-reformulated versions
FR9: Epic 4 - Users can cancel reformulation actions and retain original content
FR10: Epic 1 - Users can provide positive or negative feedback on AI-generated content
FR11: Epic 2 - Users can search notes using keyword queries that match exact text
FR12: Epic 2 - Users can search notes using natural language queries that match semantic meaning
FR13: Epic 2 - Users can view combined search results from both keyword and semantic matching
FR14: Epic 2 - Users can see visual indicators distinguishing exact matches from semantic matches
FR15: Epic 3 - Users can receive proactive insights about connections between related notes
FR16: Epic 3 - Users can view the specific content and context of suggested note connections
FR17: Epic 3 - Users can link related notes together when accepting connection suggestions
FR18: Epic 3 - Users can dismiss proactive connection insights
FR19: Epic 3 - Users can provide feedback on the relevance of suggested note connections
FR20: Epic 5 - Users can access AI settings to configure individual feature availability
FR21: Epic 1 - Users can enable or disable title suggestions independently
FR22: Epic 2 - Users can enable or disable semantic search independently
FR23: Epic 4 - Users can enable or disable paragraph reformulation independently
FR24: Epic 3 - Users can enable or disable proactive connection insights independently
FR25: Epic 3 - Users can adjust the frequency limit for proactive connection insights
FR26: Epic 5 - Users can customize AI trigger thresholds (e.g., word count for title suggestions)
FR27: Epic 5 - Users can set time period constraints for proactive connection analysis
FR28: Epic 5 - Users can temporarily disable all proactive AI features during focused work sessions
FR29: Epic 5 - Users can re-enable disabled AI features through settings interface
FR30: Epic 5 - Users can select between local AI processing (Ollama) and cloud AI processing (OpenAI)
FR31: Epic 5 - Users can verify that local AI processing does not send data external to their device
FR32: Epic 5 - Users can view connection status indicators for AI providers
FR33: Epic 5 - Users can switch between AI providers without losing functionality
FR34: Epic 5 - The system can automatically fallback to alternative AI providers if primary provider fails
FR35: Epic 5 - Users can configure API keys for cloud AI providers
FR36: Epic 5 - Users can remove stored API credentials from the system
FR37: Epic 6 - The system can detect and support multiple languages in user-generated content
FR38: Epic 6 - The system can process AI requests using user's content language while maintaining system prompts in English
FR39: Epic 7 - Administrators can configure default AI provider settings for all users
FR40: Epic 7 - Administrators can set rate limits on AI usage per user
FR41: Epic 7 - Administrators can override individual user AI settings
FR42: Epic 7 - Administrators can monitor real-time AI usage metrics across the system
FR43: Epic 7 - Administrators can view AI processing costs and consumption statistics
FR44: Epic 7 - Administrators can adjust AI model parameters (temperature, max tokens, etc.)
FR45: Epic 7 - Administrators can configure team-wide AI feature availability
FR46: Epic 7 - The system can encrypt and securely store AI provider API keys
FR47: Epic 8 - Users can access all AI features using keyboard navigation without mouse input
FR48: Epic 8 - Users can receive screen reader announcements for AI-generated content and suggestions
FR49: Epic 8 - Users can dismiss AI notifications and suggestions using keyboard shortcuts
FR50: Epic 8 - Users can view and interact with AI features on mobile devices (320px-639px)
FR51: Epic 8 - Users can view and interact with AI features on tablet devices (640px-1023px)
FR52: Epic 8 - Users can view and interact with AI features on desktop devices (1024px+)
FR53: Epic 8 - Users can perceive visual focus indicators on all interactive AI elements
FR54: Epic 8 - Users can access AI features with touch targets meeting minimum size requirements (44x44px on mobile)

## Epic List

### Epic 1: AI-Powered Title Suggestions

Users can receive intelligent title suggestions for their notes without titles, improving organization and discoverability. The system provides contextual suggestions after 50+ words without a title, allowing users to view multiple options, apply them with a single action, defer them, or dismiss them permanently. Users can also provide feedback on suggestions.

**FRs covered:** FR1, FR2, FR3, FR4, FR5, FR10, FR21

**User Outcome:** Users no longer need to manually create titles for their notes. The AI suggests relevant titles contextually, saving time and improving note organization.

**Implementation Notes:**
- Contextual trigger: After 50+ words without title
- Toast notification pattern for discovery
- 3 title suggestions generated via AI
- Feedback collection for learning
- Settings toggle for enable/disable

### Story 1.1: Database Schema Extension for Title Suggestions

As a **developer**,
I want **to extend the database schema to support AI title suggestions**,
So that **title suggestions can be stored and tracked with proper metadata**.

**Acceptance Criteria:**

**Given** the existing Note model in the database
**When** I run the Prisma migration
**Then** the Note model should have new optional fields: `autoGenerated` (Boolean), `aiProvider` (String), `aiConfidence` (Int), `language` (String), `languageConfidence` (Float), `lastAiAnalysis` (DateTime)
**And** the AiFeedback model should be created with fields: `id`, `noteId`, `userId`, `feedbackType`, `feature`, `originalContent`, `correctedContent`, `metadata`, `createdAt`
**And** all foreign key relationships should be properly defined with cascade deletion
**And** indexes should be created on `noteId`, `userId`, and `feature` fields in AiFeedback table
**And** the migration should not break any existing functionality

### Story 1.2: AI Service for Title Suggestions Generation

As a **user**,
I want **the system to generate intelligent title suggestions for my notes**,
So that **I can quickly add relevant titles without manual effort**.

**Acceptance Criteria:**

**Given** a note with content containing 50+ words and no title
**When** the title suggestion service is called
**Then** the service should generate 3 title suggestions using the configured AI provider (OpenAI or Ollama)
**And** the suggestions should be relevant to the note content
**And** the suggestions should be in the detected language of the note content
**And** the generation should complete within 2 seconds (NFR-PERF-001)
**And** the service should handle errors gracefully and return user-friendly messages
**And** the service should use the existing AI provider factory pattern

### Story 1.3: Contextual Trigger Detection for Title Suggestions

As a **user**,
I want **the system to detect when I've written enough content without a title**,
So that **title suggestions appear at the right moment without interrupting my flow**.

**Acceptance Criteria:**

**Given** I am writing a note without a title
**When** I type 50 or more words in the note content
**And** the note still has no title
**And** title suggestions are enabled in my settings
**Then** the system should detect this condition
**And** the detection should use debouncing to avoid triggering on every keystroke
**And** the detection should not block the UI or slow down typing
**And** the trigger should only fire once per note editing session until dismissed or applied

### Story 1.4: Toast Notification for Title Suggestions Discovery

As a **user**,
I want **to receive a non-intrusive notification when title suggestions are available**,
So that **I can discover the feature naturally without being overwhelmed**.

**Acceptance Criteria:**

**Given** title suggestions have been generated for my note
**When** the trigger condition is met (50+ words, no title)
**Then** a toast notification should appear with the message "I have 3 title ideas for your note, view them?"
**And** the toast should have options: "View", "Not now", "Don't ask for this note"
**And** the toast should use `role="status"` for screen reader compatibility (NFR-A11Y-010)
**And** the toast should be dismissible with the ESC key (NFR-A11Y-011)
**And** the toast should not interrupt my typing or workflow
**And** the toast should follow the contextual smart assistance pattern from UX design

### Story 1.5: Display Multiple Title Suggestions

As a **user**,
I want **to view multiple title suggestion options before selecting one**,
So that **I can choose the most appropriate title for my note**.

**Acceptance Criteria:**

**Given** I have clicked "View" on the title suggestions toast
**When** the suggestions are displayed
**Then** I should see 3 title suggestions in a dropdown or modal
**And** each suggestion should be clearly labeled and selectable
**And** the suggestions should be keyboard navigable (Arrow keys + Enter) (NFR-A11Y-001)
**And** screen readers should announce "3 title suggestions available" (NFR-A11Y-002)
**And** each suggestion should have visible focus indicators (NFR-A11Y-003)
**And** the suggestions should be responsive on mobile, tablet, and desktop (FR50, FR51, FR52)

### Story 1.6: Apply Title Suggestion to Note

As a **user**,
I want **to apply a selected title suggestion to my note with a single action**,
So that **I can quickly add a title without manual typing**.

**Acceptance Criteria:**

**Given** I am viewing the title suggestions
**When** I click or select one of the suggestions
**Then** the selected title should be applied to the note immediately
**And** the note title field should be updated with the selected suggestion
**And** the note should be saved automatically
**And** the toast notification should disappear
**And** the `autoGenerated` field should be set to `true` in the database
**And** the `aiProvider` field should record which provider was used
**And** I should receive visual feedback confirming the title was applied

### Story 1.7: Defer Title Suggestions

As a **user**,
I want **to defer viewing title suggestions to a later time**,
So that **I can continue writing without interruption**.

**Acceptance Criteria:**

**Given** I have received a title suggestions toast notification
**When** I click "Not now"
**Then** the toast should be dismissed
**And** the suggestions should be stored for later retrieval
**And** I should be able to access the suggestions again through a menu or button
**And** the system should not show the toast again for this note in the current session
**And** I can continue writing without further interruptions

### Story 1.8: Dismiss Title Suggestions Permanently

As a **user**,
I want **to permanently dismiss title suggestions for a specific note**,
So that **the system respects my choice and doesn't ask again for that note**.

**Acceptance Criteria:**

**Given** I have received a title suggestions toast notification
**When** I click "Don't ask for this note"
**Then** the toast should be dismissed immediately
**And** the system should remember this choice for this specific note
**And** the system should not show title suggestions for this note again
**And** this preference should be stored in the database (e.g., in a Note field or separate table)
**And** the choice should persist across sessions

### Story 1.9: Feedback Collection for Title Suggestions

As a **user**,
I want **to provide feedback on title suggestions**,
So that **the system can learn and improve future suggestions**.

**Acceptance Criteria:**

**Given** I have applied a title suggestion to my note
**When** I interact with the title (e.g., modify it or keep it as-is)
**Then** I should have the option to provide feedback via 👍👎 buttons
**And** when I click 👍, the system should record positive feedback in the AiFeedback table
**And** when I click 👎, the system should record negative feedback in the AiFeedback table
**And** the feedback should include metadata: `feature: 'title_suggestion'`, `originalContent`, `correctedContent` (if modified), `aiProvider`, `confidence`
**And** the feedback should be stored with proper user and note associations
**And** the feedback UI should be accessible via keyboard (NFR-A11Y-001)

### Story 1.10: Settings Toggle for Title Suggestions

As a **user**,
I want **to enable or disable title suggestions in my AI settings**,
So that **I have control over when this feature is active**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page (`/settings/ai`)
**When** I view the title suggestions setting
**Then** I should see a toggle switch labeled "Title Suggestions"
**And** the toggle should have a description: "Suggest titles for untitled notes after 50+ words"
**And** when I toggle it ON, title suggestions should be enabled
**And** when I toggle it OFF, title suggestions should be disabled
**And** the setting should be saved immediately to the UserAISettings table
**And** the change should take effect immediately (no page refresh needed)
**And** the toggle should be keyboard accessible (NFR-A11Y-001)

### Epic 2: Hybrid Semantic Search

Users can search their notes using both keyword queries and natural language queries that match semantic meaning. The system combines results from both approaches, displaying visual indicators to distinguish exact matches from semantic matches. This enables users to find notes even when they don't remember exact keywords.

**FRs covered:** FR11, FR12, FR13, FR14, FR22

**User Outcome:** Users can find their notes more easily using natural language queries, not just exact keywords. The hybrid approach ensures comprehensive search results.

**Implementation Notes:**
- Unified search interface (no distinction visible to user)
- Badges: "Exact Match" | "Semantic Match"
- Reciprocal Rank Fusion (RRF) for result ranking
- Performance target: < 300ms for 1000 notes
- Settings toggle for enable/disable

### Story 2.1: Semantic Search Service Implementation

As a **user**,
I want **to search my notes using natural language queries that match semantic meaning**,
So that **I can find notes even when I don't remember exact keywords**.

**Acceptance Criteria:**

**Given** I have notes with embeddings stored in the database
**When** I perform a semantic search query
**Then** the service should generate an embedding for my query using the AI provider
**And** the service should calculate cosine similarity between the query embedding and all note embeddings
**And** the service should return results ranked by similarity score
**And** the search should complete within 300ms for up to 1000 notes (NFR-PERF-002)
**And** the service should handle errors gracefully and return user-friendly messages
**And** the service should use the existing AI provider factory pattern

### Story 2.2: Keyword Search Implementation

As a **user**,
I want **to search my notes using keyword queries that match exact text**,
So that **I can quickly find notes containing specific words or phrases**.

**Acceptance Criteria:**

**Given** I have notes in the database
**When** I perform a keyword search query
**Then** the service should search note titles, content, and labels for exact keyword matches
**And** the service should return results ranked by relevance (title matches first, then content, then labels)
**And** the search should be case-insensitive
**And** the search should support partial word matches
**And** the search should complete within 300ms for up to 1000 notes
**And** the service should handle special characters and escape them properly

### Story 2.3: Hybrid Search Result Fusion

As a **user**,
I want **to see combined search results from both keyword and semantic matching**,
So that **I get comprehensive search results that cover both exact matches and related content**.

**Acceptance Criteria:**

**Given** I perform a search query
**When** both keyword and semantic search are enabled
**Then** the system should execute both searches in parallel
**And** the system should use Reciprocal Rank Fusion (RRF) to combine the results
**And** the combined results should be ranked by the fusion score
**And** duplicate notes should appear only once in the results
**And** the total search time should remain under 300ms (NFR-PERF-002)
**And** the results should be limited to the top 10 most relevant notes

### Story 2.4: Visual Indicators for Search Result Types

As a **user**,
I want **to see visual indicators distinguishing exact matches from semantic matches**,
So that **I understand why each result appears in my search**.

**Acceptance Criteria:**

**Given** I have performed a hybrid search
**When** the results are displayed
**Then** each result should display a badge indicating its match type
**And** results from keyword search should show "Exact Match" badge
**And** results from semantic search should show "Semantic Match" badge
**And** results that match both should show both badges
**And** the badges should use color coding (blue gradient for semantic, different color for exact)
**And** the badges should be accessible to screen readers (NFR-A11Y-004)
**And** the badges should be visible on mobile, tablet, and desktop (FR50, FR51, FR52)

### Story 2.5: Unified Search Interface

As a **user**,
I want **a single search interface that works for both keyword and semantic queries**,
So that **I don't need to think about which search type to use**.

**Acceptance Criteria:**

**Given** I am on the main notes page
**When** I use the search bar
**Then** I should see a single search input field
**And** the search should automatically use both keyword and semantic matching
**And** I should not need to select a search type
**And** the search should work as I type (with debouncing)
**And** the results should update in real-time
**And** the search interface should be keyboard accessible (NFR-A11Y-001)
**And** the search should be responsive on all device sizes (FR50, FR51, FR52)

### Story 2.6: Settings Toggle for Semantic Search

As a **user**,
I want **to enable or disable semantic search in my AI settings**,
So that **I can control whether semantic matching is used in my searches**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page (`/settings/ai`)
**When** I view the semantic search setting
**Then** I should see a toggle switch labeled "Semantic Search"
**And** the toggle should have a description: "Find notes by meaning, not just keywords"
**And** when I toggle it ON, semantic search should be enabled
**And** when I toggle it OFF, only keyword search should be used
**And** the setting should be saved immediately to the UserAISettings table
**And** the change should take effect immediately (no page refresh needed)
**And** the toggle should be keyboard accessible (NFR-A11Y-001)

### Epic 3: Memory Echo - Proactive Connections

Users discover proactive connections between their notes that they hadn't seen before. The system analyzes note embeddings in the background and surfaces up to 1 insight per day (configurable 0-3), displaying two connected notes side-by-side. Users can view connections, link notes together, dismiss insights, or provide feedback.

**FRs covered:** FR15, FR16, FR17, FR18, FR19, FR24, FR25

**User Outcome:** Users experience the "Aha!" moment when the system reveals unexpected connections between their notes, enhancing knowledge discovery and organization.

**Implementation Notes:**
- Background processing (< 100ms UI freeze)
- Cosine similarity threshold > 0.75
- Max 1 insight/day (configurable 0-3)
- Time diversity filter (notes from different periods)
- Feedback learning system (👍👎 buttons)
- Settings toggle and frequency slider

### Story 3.1: Database Schema for Memory Echo Insights

As a **developer**,
I want **to create the database schema for Memory Echo insights**,
So that **proactive connections between notes can be stored and tracked**.

**Acceptance Criteria:**

**Given** the existing database schema
**When** I run the Prisma migration
**Then** the MemoryEchoInsight model should be created with fields: `id`, `userId`, `note1Id`, `note2Id`, `similarityScore`, `insightDate`, `viewed`, `feedback`
**And** foreign key relationships should be properly defined with cascade deletion
**And** a unique constraint should ensure max 1 insight per user per day: `@@unique([userId, insightDate])`
**And** indexes should be created on `userId` and `insightDate` for efficient queries
**And** the migration should not break any existing functionality

### Story 3.2: Memory Echo Background Analysis Service

As a **user**,
I want **the system to analyze my notes in the background to find connections**,
So that **I can discover relationships between my notes without manual effort**.

**Acceptance Criteria:**

**Given** I have notes with embeddings in the database
**When** the Memory Echo service runs in the background
**Then** the service should calculate cosine similarity between all note pairs
**And** the service should filter results by similarity threshold (> 0.75)
**And** the service should apply time diversity filter (notes from different time periods)
**And** the service should select the top connection that hasn't been shown today
**And** the analysis should complete with less than 100ms UI thread blocking (NFR-PERF-003)
**And** the service should store the insight in the MemoryEchoInsight table
**And** the service should handle errors gracefully without exposing them to users

### Story 3.3: Memory Echo Insight Notification

As a **user**,
I want **to receive proactive notifications about connections between my notes**,
So that **I can discover relationships I hadn't noticed**.

**Acceptance Criteria:**

**Given** a Memory Echo insight has been generated for me
**When** I log in or the insight becomes available
**Then** I should receive a notification: "I noticed something..."
**And** the notification should display the two connected notes side-by-side
**And** the notification should show a preview of each note's content
**And** the notification should indicate the similarity score or connection strength
**And** the notification should be non-intrusive and dismissible
**And** the notification should use `role="status"` for screen readers (NFR-A11Y-010)
**And** the notification should be keyboard accessible (NFR-A11Y-001)
**And** the notification should be responsive on all device sizes (FR50, FR51, FR52)

### Story 3.4: View Memory Echo Connection Details

As a **user**,
I want **to view the specific content and context of suggested note connections**,
So that **I can understand why these notes are connected**.

**Acceptance Criteria:**

**Given** I have received a Memory Echo notification
**When** I click "View Connection" or interact with the notification
**Then** I should see a detailed view showing both notes side-by-side
**And** I should see the full content of both notes
**And** I should see highlighting or indicators showing the related sections
**And** I should see the similarity score or connection strength
**And** I should have options to link the notes, dismiss, or provide feedback
**And** the view should be accessible via keyboard navigation (NFR-A11Y-001)
**And** the view should be responsive on all device sizes (FR50, FR51, FR52)

### Story 3.5: Link Notes from Memory Echo

As a **user**,
I want **to link related notes together when accepting connection suggestions**,
So that **I can create explicit relationships between my notes**.

**Acceptance Criteria:**

**Given** I am viewing a Memory Echo connection
**When** I click "Link Notes" or accept the connection
**Then** the system should create a link or relationship between the two notes
**And** the link should be stored in the database
**And** I should receive visual feedback confirming the link was created
**And** the Memory Echo insight should be marked as viewed
**And** the notification should be dismissed
**And** the link should be visible when viewing either note in the future

### Story 3.6: Dismiss Memory Echo Insights

As a **user**,
I want **to dismiss proactive connection insights**,
So that **I can control which insights I see**.

**Acceptance Criteria:**

**Given** I have received a Memory Echo notification
**When** I click "Dismiss"
**Then** the notification should be dismissed immediately
**And** the insight should be marked as viewed in the database
**And** the system should not show this specific insight again
**And** I should be able to continue working without interruption
**And** the dismissal should be saved immediately

### Story 3.7: Feedback Collection for Memory Echo

As a **user**,
I want **to provide feedback on the relevance of suggested note connections**,
So that **the system can learn and improve future suggestions**.

**Acceptance Criteria:**

**Given** I am viewing a Memory Echo connection
**When** I interact with the feedback buttons
**Then** I should see 👍 and 👎 buttons
**And** when I click 👍, the system should record positive feedback in the MemoryEchoInsight table
**And** when I click 👎, the system should record negative feedback
**And** the feedback should be stored with the insight record
**And** the feedback should be used to improve future connection suggestions
**And** the feedback buttons should be keyboard accessible (NFR-A11Y-001)
**And** the feedback buttons should meet minimum touch target size on mobile (44x44px) (NFR-A11Y-005)

### Story 3.8: Settings Toggle and Frequency Control for Memory Echo

As a **user**,
I want **to enable or disable Memory Echo and control its frequency**,
So that **I can customize how often I receive proactive insights**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page (`/settings/ai`)
**When** I view the Memory Echo setting
**Then** I should see a toggle switch labeled "Memory Echo"
**And** the toggle should have a description: "Daily proactive connections between your notes"
**And** when the toggle is ON, I should see a frequency slider
**And** the frequency slider should allow values from 0 to 3 insights per day
**And** when I adjust the slider, the setting should be saved immediately
**And** when I toggle it OFF, Memory Echo should be disabled completely
**And** the settings should be saved to the UserAISettings table
**And** the changes should take effect immediately
**And** all controls should be keyboard accessible (NFR-A11Y-001)

### Epic 4: Paragraph-Level AI Reformulation

Users can improve their note content using AI-powered reformulation. They can select a paragraph and choose from different reformulation approaches (clarify, shorten, improve style), then replace the original content or cancel the action. This helps users refine their writing.

**FRs covered:** FR6, FR7, FR8, FR9, FR23

**User Outcome:** Users can enhance their note content quality with AI assistance, making their notes clearer, more concise, or better styled.

**Implementation Notes:**
- Menu "..." on note card → "AI Assist" → "Rewrite paragraph"
- Modal for paragraph selection
- Three reformulation options
- Undo/cancel functionality
- Feedback collection
- Settings toggle for enable/disable

### Story 4.1: Paragraph Selection Interface

As a **user**,
I want **to select a paragraph from my note for AI reformulation**,
So that **I can improve specific sections of my content**.

**Acceptance Criteria:**

**Given** I am viewing or editing a note
**When** I click the "..." menu on the note card
**Then** I should see an "AI Assist" option
**And** when I click "AI Assist", I should see "Rewrite paragraph" option
**And** when I click "Rewrite paragraph", a modal should open
**And** the modal should display my note content with paragraph boundaries
**And** I should be able to click on a paragraph to select it
**And** the selected paragraph should be visually highlighted
**And** the modal should be keyboard accessible (NFR-A11Y-001)
**And** the modal should be responsive on all device sizes (FR50, FR51, FR52)

### Story 4.2: Reformulation Options Selection

As a **user**,
I want **to choose different reformulation approaches for my paragraph**,
So that **I can get the type of improvement I need**.

**Acceptance Criteria:**

**Given** I have selected a paragraph for reformulation
**When** the reformulation options are displayed
**Then** I should see three options: "Clarify", "Raccourcir" (Shorten), "Améliorer style" (Improve style)
**And** each option should have a clear description
**And** I should be able to select one option
**And** the options should be keyboard navigable (NFR-A11Y-001)
**And** the options should meet minimum touch target size on mobile (44x44px) (NFR-A11Y-005)

### Story 4.3: AI Paragraph Reformulation Service

As a **user**,
I want **the system to reformulate my selected paragraph using AI**,
So that **I can improve the clarity, length, or style of my content**.

**Acceptance Criteria:**

**Given** I have selected a paragraph and a reformulation option
**When** I trigger the reformulation
**Then** the system should call the AI service with the paragraph content and selected option
**And** the AI should generate a reformulated version based on the option
**And** the reformulation should complete within 5 seconds for content up to 500 words (NFR-PERF-004)
**And** the system should show a loading indicator during processing
**And** the system should handle errors gracefully with user-friendly messages
**And** the service should use the configured AI provider (OpenAI or Ollama)

### Story 4.4: Display Reformulated Content

As a **user**,
I want **to see the reformulated version of my paragraph**,
So that **I can review it before applying**.

**Acceptance Criteria:**

**Given** the AI has generated a reformulated paragraph
**When** the reformulation is complete
**Then** I should see a side-by-side or before/after view
**And** the original paragraph should be clearly labeled
**And** the reformulated paragraph should be clearly labeled
**And** I should have options to "Apply", "Cancel", or "Try again"
**And** the view should be accessible via keyboard (NFR-A11Y-001)
**And** screen readers should announce the reformulated content (NFR-A11Y-002)
**And** the view should be responsive on all device sizes (FR50, FR51, FR52)

### Story 4.5: Apply Reformulated Content

As a **user**,
I want **to replace my original paragraph with the AI-reformulated version**,
So that **I can improve my note content**.

**Acceptance Criteria:**

**Given** I am viewing the reformulated paragraph
**When** I click "Apply"
**Then** the original paragraph in my note should be replaced with the reformulated version
**And** the note should be saved automatically
**And** the modal should close
**And** I should receive visual feedback confirming the change
**And** the change should be recorded in the database (e.g., `autoGenerated: true`)
**And** I should have the option to undo the change

### Story 4.6: Cancel Reformulation Action

As a **user**,
I want **to cancel a reformulation action and retain my original content**,
So that **I can keep my original writing if I don't like the reformulation**.

**Acceptance Criteria:**

**Given** I am viewing a reformulated paragraph
**When** I click "Cancel"
**Then** the modal should close
**And** my original note content should remain unchanged
**And** no changes should be saved to the database
**And** I should be able to try reformulation again later if desired

### Story 4.7: Feedback Collection for Reformulation

As a **user**,
I want **to provide feedback on reformulated content**,
So that **the system can learn and improve future reformulations**.

**Acceptance Criteria:**

**Given** I have applied a reformulated paragraph
**When** I interact with the feedback options
**Then** I should see 👍 and 👎 buttons
**And** when I click 👍, the system should record positive feedback in the AiFeedback table
**And** when I click 👎, the system should record negative feedback
**And** the feedback should include metadata: `feature: 'paragraph_refactor'`, `originalContent`, `correctedContent`, `aiProvider`
**And** the feedback should be stored with proper user and note associations
**And** the feedback buttons should be keyboard accessible (NFR-A11Y-001)

### Story 4.8: Settings Toggle for Paragraph Reformulation

As a **user**,
I want **to enable or disable paragraph reformulation in my AI settings**,
So that **I can control whether this feature is available**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page (`/settings/ai`)
**When** I view the paragraph reformulation setting
**Then** I should see a toggle switch labeled "Paragraph Reformulation"
**And** the toggle should have a description: "Improve paragraph clarity, length, or style"
**And** when I toggle it ON, the reformulation feature should be enabled
**And** when I toggle it OFF, the "Rewrite paragraph" option should be hidden
**And** the setting should be saved immediately to the UserAISettings table
**And** the change should take effect immediately
**And** the toggle should be keyboard accessible (NFR-A11Y-001)

### Epic 5: AI Settings & Privacy Control

Users have complete control over all AI features with granular ON/OFF toggles for each feature. They can customize trigger thresholds, set time period constraints, and temporarily disable all proactive AI features. Most importantly, users can choose between local AI processing (Ollama) and cloud AI processing (OpenAI), with clear indicators showing connection status and privacy implications.

**FRs covered:** FR20, FR26, FR27, FR28, FR29, FR30, FR31, FR32, FR33, FR34, FR35, FR36

**User Outcome:** Users feel in control of their AI experience and can choose privacy-first local processing or cloud processing based on their preferences. All choices are transparent and verifiable.

**Implementation Notes:**
- Dedicated UserAISettings table
- Granular feature toggles (title suggestions, semantic search, reformulation, Memory Echo)
- Memory Echo frequency slider (0-3/day)
- AI provider selection (Ollama/OpenAI/Auto)
- Connection status indicators
- API key management (encrypted storage)
- Auto-fallback between providers
- Verifiable local processing (DevTools inspection)

### Story 5.1: Database Schema for AI Settings

As a **developer**,
I want **to create the database schema for user AI settings**,
So that **user preferences for AI features can be stored and retrieved**.

**Acceptance Criteria:**

**Given** the existing database schema
**When** I run the Prisma migration
**Then** the UserAISettings model should be created with fields: `userId` (primary key), `titleSuggestions`, `semanticSearch`, `paragraphRefactor`, `memoryEcho`, `memoryEchoFrequency`, `aiProvider`
**And** the model should have a one-to-one relationship with the User model
**And** default values should be set: `titleSuggestions: true`, `semanticSearch: true`, `paragraphRefactor: true`, `memoryEcho: true`, `memoryEchoFrequency: 'daily'`, `aiProvider: 'auto'`
**And** indexes should be created on `memoryEcho`, `aiProvider`, and `memoryEchoFrequency` for analytics queries
**And** the migration should not break any existing functionality

### Story 5.2: AI Settings Page Structure

As a **user**,
I want **to access a dedicated AI settings page**,
So that **I can configure all AI features in one place**.

**Acceptance Criteria:**

**Given** I am logged into the application
**When** I navigate to `/settings/ai`
**Then** I should see a page titled "AI Settings"
**And** the page should be organized into clear sections
**And** the page should display all AI feature toggles
**And** the page should show AI provider selection
**And** the page should be accessible via keyboard navigation (NFR-A11Y-001)
**And** the page should be responsive on all device sizes (FR50, FR51, FR52)
**And** the page should follow the settings UX design from Story 11.2

### Story 5.3: Granular Feature Toggles

As a **user**,
I want **to enable or disable each AI feature independently**,
So that **I have complete control over which AI features are active**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page
**When** I view the feature toggles section
**Then** I should see toggles for: Title Suggestions, Semantic Search, Paragraph Reformulation, Memory Echo
**And** each toggle should have a clear label and description
**When** I toggle a feature ON or OFF
**Then** the setting should be saved immediately to the UserAISettings table
**And** the change should take effect immediately (no page refresh needed)
**And** I should receive visual feedback confirming the save
**And** all toggles should be keyboard accessible (NFR-A11Y-001)

### Story 5.4: Customize AI Trigger Thresholds

As a **user**,
I want **to customize AI trigger thresholds (e.g., word count for title suggestions)**,
So that **I can control when AI features are activated**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page
**When** I view the trigger thresholds section
**Then** I should see options to customize thresholds for each feature
**And** for title suggestions, I should be able to set the word count threshold (default: 50)
**And** for Memory Echo, I should be able to set time period constraints
**When** I change a threshold value
**Then** the setting should be saved immediately
**And** the change should take effect for future AI interactions
**And** the controls should be keyboard accessible (NFR-A11Y-001)

### Story 5.5: Focus Mode Toggle

As a **user**,
I want **to temporarily disable all proactive AI features during focused work sessions**,
So that **I can work without interruptions**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page
**When** I view the Focus Mode option
**Then** I should see a toggle labeled "Focus Mode" or "Disable All Proactive AI"
**And** the toggle should have a description explaining it temporarily disables proactive features
**When** I enable Focus Mode
**Then** all proactive AI features (title suggestions, Memory Echo) should be disabled
**And** on-demand features (search, reformulation) should remain available
**When** I disable Focus Mode
**Then** all previously enabled features should be re-enabled
**And** the setting should be saved immediately

### Story 5.6: AI Provider Selection

As a **user**,
I want **to select between local AI processing (Ollama) and cloud AI processing (OpenAI)**,
So that **I can choose based on my privacy preferences and needs**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page
**When** I view the AI Provider section
**Then** I should see options: "Auto (Recommended)", "Ollama (Local)", "OpenAI (Cloud)"
**And** each option should have a clear description
**And** "Auto" should be described as "Ollama when available, OpenAI fallback"
**And** "Ollama (Local)" should be described as "100% private, runs locally"
**And** "OpenAI (Cloud)" should be described as "Most accurate, requires API key"
**When** I select a provider
**Then** the setting should be saved immediately to UserAISettings table
**And** the system should attempt to use the selected provider
**And** the selection should be keyboard accessible (NFR-A11Y-001)

### Story 5.7: Connection Status Indicators

As a **user**,
I want **to view connection status indicators for AI providers**,
So that **I know if my selected provider is available and working**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page
**When** I view the AI Provider section
**Then** I should see connection status indicators for each provider
**And** the indicator should show "✅ Connected" when the provider is available
**And** the indicator should show "❌ Not Available" when the provider is unavailable
**And** for Ollama, the indicator should show the endpoint (e.g., "http://localhost:11434")
**And** for OpenAI, the indicator should show "Cloud" or "API Key Configured"
**And** the status should update automatically when providers become available/unavailable
**And** the indicators should be accessible to screen readers (NFR-A11Y-002)

### Story 5.8: API Key Management for Cloud Providers

As a **user**,
I want **to configure and manage API keys for cloud AI providers**,
So that **I can use OpenAI or other cloud services securely**.

**Acceptance Criteria:**

**Given** I am on the AI Settings page
**And** I have selected OpenAI as my provider
**When** I view the API Key section
**Then** I should see an input field for entering my OpenAI API key
**And** the input should be masked (password type) for security
**When** I enter and save an API key
**Then** the key should be encrypted and stored securely in the database (NFR-SEC-004)
**And** the key should never be displayed in plain text
**And** I should receive confirmation that the key was saved
**And** I should have an option to remove/delete the stored key
**When** I remove the API key
**Then** the key should be deleted from the database
**And** I should receive confirmation of deletion

### Story 5.9: Verify Local Processing (Privacy Verification)

As a **user**,
I want **to verify that local AI processing does not send data external to my device**,
So that **I can trust that my data remains private**.

**Acceptance Criteria:**

**Given** I have selected Ollama as my AI provider
**When** I use any AI feature (title suggestions, search, etc.)
**Then** I should be able to verify in browser DevTools (Network tab) that no external API calls are made
**And** all AI processing should use only `localhost:11434` (Ollama endpoint)
**And** no calls should be made to external services (no OpenAI, no Google, etc.)
**And** the connection status indicator should confirm "Local Processing"
**And** the system should provide clear messaging that data never leaves the device

### Story 5.10: Auto-Fallback Between Providers

As a **user**,
I want **the system to automatically fallback to alternative AI providers if my primary provider fails**,
So that **AI features continue working even if one provider is unavailable**.

**Acceptance Criteria:**

**Given** I have selected a primary AI provider (e.g., Ollama)
**When** the primary provider becomes unavailable or returns an error
**Then** the system should automatically attempt to use the fallback provider
**And** if "Auto" is selected, it should try Ollama first, then OpenAI
**And** the system should display a notification about the fallback
**And** the connection status indicators should update to reflect the active provider
**And** AI features should continue working seamlessly
**And** the fallback should be transparent to the user (no error messages unless both fail)

### Story 5.11: Re-enable Disabled Features

As a **user**,
I want **to re-enable disabled AI features through the settings interface**,
So that **I can easily restore features I previously turned off**.

**Acceptance Criteria:**

**Given** I have previously disabled one or more AI features
**When** I return to the AI Settings page
**Then** I should see the current state of all toggles (ON/OFF)
**When** I toggle a disabled feature back ON
**Then** the feature should be immediately re-enabled
**And** the setting should be saved to the database
**And** the feature should become available for use immediately
**And** I should receive visual feedback confirming the change

### Epic 6: Language Detection & Multilingual Support

The system automatically detects the language of user-generated content and processes AI requests accordingly. System prompts remain in English for stability, while user content is processed in its detected language. This enables seamless multilingual support without user configuration.

**FRs covered:** FR37, FR38

**User Outcome:** Users can write notes in any supported language (FR, EN, ES, DE, FA, etc.) and the AI will understand and respond appropriately without manual language selection.

**Implementation Notes:**
- Hybrid detection: TinyLD for short notes, AI for long notes (≥50 words)
- 62 languages supported via TinyLD
- Language stored in Note.language field
- System prompts in English, user data in local language
- Automatic detection on note creation/update

### Story 6.1: Language Detection Service Implementation

As a **user**,
I want **the system to automatically detect the language of my note content**,
So that **AI features can process my content in the correct language**.

**Acceptance Criteria:**

**Given** I create or update a note with content
**When** the note is saved
**Then** the system should automatically detect the language of the content
**And** for short notes (< 50 words), the system should use TinyLD library for fast detection
**And** for long notes (≥ 50 words), the system should use AI for more accurate detection
**And** the detected language should be stored in the `Note.language` field (ISO 639-1 code: 'fr', 'en', 'es', 'de', 'fa', etc.)
**And** the detection confidence should be stored in `Note.languageConfidence` field (0.0-1.0)
**And** the system should support at least 62 languages via TinyLD
**And** the detection should complete quickly without blocking the UI

### Story 6.2: Multilingual AI Processing

As a **user**,
I want **the system to process AI requests using my content's language while keeping system prompts in English**,
So that **AI features work correctly with my multilingual content**.

**Acceptance Criteria:**

**Given** I have a note with content in a detected language (e.g., French)
**When** I use any AI feature (title suggestions, reformulation, etc.)
**Then** the system should use the detected language for processing the user content
**And** the system prompts sent to the AI should remain in English for stability
**And** the AI should generate responses in the same language as the input content
**And** the system should handle language switching automatically
**And** the language detection should be transparent to the user (no manual selection needed)

### Epic 7: Admin Dashboard & Analytics

Administrators can configure default AI provider settings for all users, set rate limits, override individual user settings, and monitor real-time AI usage metrics. They can view processing costs, adjust model parameters, and configure team-wide feature availability. All API keys are encrypted and securely stored.

**FRs covered:** FR39, FR40, FR41, FR42, FR43, FR44, FR45, FR46

**User Outcome:** Administrators can effectively manage AI usage across their team, control costs, and ensure optimal performance and security.

**Implementation Notes:**
- Admin-only dashboard
- Real-time metrics (usage, costs, response times)
- Per-user rate limiting
- Team-wide configuration with user overrides
- Cost tracking and billing estimation
- Model parameter adjustment
- Encrypted API key storage

### Story 7.1: Admin Dashboard Access Control

As an **administrator**,
I want **to access an admin-only dashboard for AI management**,
So that **I can monitor and configure AI usage for my team**.

**Acceptance Criteria:**

**Given** I am logged in as an administrator
**When** I navigate to the admin dashboard
**Then** I should see an "AI Management" or "AI Analytics" section
**And** only users with admin role should be able to access this section (NFR-SEC-011)
**And** non-admin users should receive an "Access Denied" message if they try to access it
**And** the dashboard should display real-time AI usage metrics
**And** the dashboard should be accessible via keyboard navigation (NFR-A11Y-001)

### Story 7.2: Real-Time AI Usage Metrics

As an **administrator**,
I want **to monitor real-time AI usage metrics across the system**,
So that **I can understand how AI features are being used**.

**Acceptance Criteria:**

**Given** I am on the admin AI dashboard
**When** I view the metrics section
**Then** I should see metrics including: total AI requests today, average response time, top features used, Memory Echo feedback ratio
**And** the metrics should update in real-time or refresh automatically
**And** I should be able to filter metrics by date range
**And** I should be able to view metrics per user or aggregated
**And** the metrics should be displayed in clear charts or tables
**And** the data should be accessible to screen readers (NFR-A11Y-002)

### Story 7.3: Configure Default AI Provider Settings

As an **administrator**,
I want **to configure default AI provider settings for all users**,
So that **I can set team-wide standards for AI usage**.

**Acceptance Criteria:**

**Given** I am on the admin AI dashboard
**When** I view the default settings section
**Then** I should see options to set default AI provider (Auto, Ollama, OpenAI)
**And** I should be able to configure default feature toggles for all users
**And** when I save default settings
**Then** new users should receive these defaults
**And** existing users should keep their current settings unless overridden
**And** the settings should be saved to a system configuration table

### Story 7.4: Set Rate Limits Per User

As an **administrator**,
I want **to set rate limits on AI usage per user**,
So that **I can control costs and prevent abuse**.

**Acceptance Criteria:**

**Given** I am on the admin AI dashboard
**When** I view the rate limits section
**Then** I should see options to set maximum AI requests per minute per user
**And** I should be able to set different limits for different users or user groups
**And** I should be able to set a default rate limit for all users
**When** I save rate limit settings
**Then** the system should enforce these limits (NFR-SEC-014)
**And** users exceeding limits should receive appropriate error messages
**And** the limits should be stored in the database

### Story 7.5: Override Individual User AI Settings

As an **administrator**,
I want **to override individual user AI settings**,
So that **I can customize AI behavior for specific users or troubleshoot issues**.

**Acceptance Criteria:**

**Given** I am on the admin AI dashboard
**When** I select a specific user
**Then** I should see their current AI settings
**And** I should be able to modify any setting (provider, feature toggles, thresholds)
**When** I save overrides
**Then** the user's settings should be updated immediately
**And** the overrides should take precedence over default settings
**And** I should be able to remove overrides to restore defaults
**And** the user should be notified of the change (optional)

### Story 7.6: View AI Processing Costs and Statistics

As an **administrator**,
I want **to view AI processing costs and consumption statistics**,
So that **I can monitor expenses and optimize usage**.

**Acceptance Criteria:**

**Given** I am on the admin AI dashboard
**When** I view the costs section
**Then** I should see estimated costs for cloud AI usage (OpenAI)
**And** I should see consumption statistics: total tokens used, number of requests, average cost per request
**And** I should be able to filter costs by date range, user, or feature
**And** I should see cost trends over time (charts)
**And** local AI usage (Ollama) should show as $0 cost
**And** the cost data should be stored and aggregated from usage logs

### Story 7.7: Adjust AI Model Parameters

As an **administrator**,
I want **to adjust AI model parameters (temperature, max tokens, etc.)**,
So that **I can fine-tune AI behavior for my team's needs**.

**Acceptance Criteria:**

**Given** I am on the admin AI dashboard
**When** I view the model parameters section
**Then** I should see options to adjust: temperature, max tokens, top_p, frequency_penalty, etc.
**And** each parameter should have a description and valid range
**And** I should be able to set different parameters for different features
**When** I save parameter changes
**Then** the new parameters should be used for all future AI requests
**And** the parameters should be stored in system configuration
**And** changes should take effect immediately

### Story 7.8: Configure Team-Wide AI Feature Availability

As an **administrator**,
I want **to configure team-wide AI feature availability**,
So that **I can enable or disable features for all users at once**.

**Acceptance Criteria:**

**Given** I am on the admin AI dashboard
**When** I view the feature availability section
**Then** I should see toggles for each AI feature (Title Suggestions, Semantic Search, Reformulation, Memory Echo)
**And** I should be able to enable or disable features for all users
**When** I disable a feature team-wide
**Then** all users should have that feature disabled (overriding individual settings)
**And** users should see the feature as unavailable in their settings
**When** I re-enable a feature
**Then** users' previous individual settings should be restored
**And** the changes should take effect immediately

### Story 7.9: Encrypted API Key Storage

As an **administrator**,
I want **API keys to be encrypted and securely stored**,
So that **sensitive credentials are protected**.

**Acceptance Criteria:**

**Given** I am configuring API keys for cloud AI providers
**When** I save an API key
**Then** the key should be encrypted before storage in the database (NFR-SEC-004)
**And** the encryption should use industry-standard algorithms
**And** the key should never be displayed in plain text
**And** the key should only be decrypted when needed for API calls
**And** decrypted keys should never be logged or exposed in error messages
**And** the encryption keys should be stored securely (environment variables, not in code)

### Epic 8: Accessibility & Responsive Design

All AI features are accessible to users on all devices (mobile, tablet, desktop) with full keyboard navigation support, screen reader compatibility, and proper touch targets. The interface adapts responsively to different screen sizes while maintaining functionality and usability.

**FRs covered:** FR47, FR48, FR49, FR50, FR51, FR52, FR53, FR54

**User Outcome:** All users, regardless of device or accessibility needs, can fully access and use all AI features with an optimal experience.

**Implementation Notes:**
- WCAG 2.1 Level AA compliance
- Keyboard-only navigation (Tab, Enter, ESC)
- Screen reader announcements (ARIA labels)
- Touch targets ≥44x44px on mobile
- Responsive layouts (mobile-first approach)
- Focus indicators (3:1 contrast ratio)
- Toast notifications with role="status"
- Mobile (320px-639px), Tablet (640px-1023px), Desktop (1024px+)

### Story 8.1: Keyboard Navigation for All AI Features

As a **user**,
I want **to access all AI features using keyboard navigation without mouse input**,
So that **I can use the application efficiently with keyboard-only input**.

**Acceptance Criteria:**

**Given** I am using the application with keyboard only
**When** I navigate through AI features (title suggestions, search, reformulation, Memory Echo, settings)
**Then** I should be able to access all interactive elements using Tab key
**And** I should be able to activate buttons and toggles using Enter or Space
**And** I should be able to close modals and dismiss notifications using ESC key
**And** I should be able to navigate dropdowns and lists using Arrow keys
**And** there should be no keyboard traps (I can always navigate away)
**And** the tab order should be logical and intuitive
**And** all functionality should work identically to mouse interaction (NFR-A11Y-001)

### Story 8.2: Screen Reader Support for AI Features

As a **user with visual impairments**,
I want **to receive screen reader announcements for AI-generated content and suggestions**,
So that **I can understand and interact with AI features using assistive technology**.

**Acceptance Criteria:**

**Given** I am using a screen reader (NVDA, JAWS, VoiceOver)
**When** AI features generate content or suggestions
**Then** screen readers should announce: "3 title suggestions available", "Search found 5 results", "Memory Echo connection found", etc.
**And** all AI-generated content should have descriptive text labels
**And** buttons should have accessible names (not just icons)
**And** form inputs should have associated labels
**And** status messages should use appropriate ARIA roles (`role="status"` for toasts, not `role="alert"`)
**And** the announcements should be clear and informative (NFR-A11Y-002)

### Story 8.3: Keyboard Shortcuts for AI Notifications

As a **user**,
I want **to dismiss AI notifications and suggestions using keyboard shortcuts**,
So that **I can quickly manage notifications without mouse interaction**.

**Acceptance Criteria:**

**Given** I have received an AI notification (toast, Memory Echo, etc.)
**When** I press the ESC key
**Then** the notification should be dismissed immediately
**And** the focus should return to the previous element
**And** the dismissal should work for all types of AI notifications
**And** the ESC key should also close modals and dialogs
**And** the keyboard shortcut should be documented or discoverable (NFR-A11Y-011)

### Story 8.4: Mobile Responsive Design for AI Features

As a **user on a mobile device**,
I want **to view and interact with AI features on my mobile device (320px-639px)**,
So that **I can use all AI capabilities on the go**.

**Acceptance Criteria:**

**Given** I am using the application on a mobile device (320px-639px viewport)
**When** I access AI features
**Then** all AI features should be fully functional and usable
**And** the layout should adapt to the smaller screen (mobile-first design)
**And** touch targets should meet minimum size requirements (44x44px) (NFR-A11Y-005)
**And** spacing between touch targets should be at least 8px (NFR-A11Y-006)
**And** text should be readable without zooming
**And** modals should be full-screen or appropriately sized for mobile
**And** the experience should be optimized for touch interaction (FR50)

### Story 8.5: Tablet Responsive Design for AI Features

As a **user on a tablet device**,
I want **to view and interact with AI features on my tablet device (640px-1023px)**,
So that **I can use AI features comfortably on a medium-sized screen**.

**Acceptance Criteria:**

**Given** I am using the application on a tablet device (640px-1023px viewport)
**When** I access AI features
**Then** all AI features should be fully functional and usable
**And** the layout should be optimized for tablet screen size
**And** touch targets should still meet minimum size requirements (44x44px)
**And** the interface should take advantage of the larger screen space
**And** the experience should support both touch and keyboard interaction
**And** the design should be comfortable for reading and interaction (FR51)

### Story 8.6: Desktop Responsive Design for AI Features

As a **user on a desktop device**,
I want **to view and interact with AI features on my desktop device (1024px+)**,
So that **I can use AI features efficiently with mouse and keyboard**.

**Acceptance Criteria:**

**Given** I am using the application on a desktop device (1024px+ viewport)
**When** I access AI features
**Then** all AI features should be fully functional and usable
**And** the layout should take advantage of the larger screen space
**And** the interface should be optimized for mouse and keyboard interaction
**And** keyboard shortcuts should be available and efficient
**And** the design should support power user workflows
**And** multiple AI features should be accessible without excessive scrolling (FR52)

### Story 8.7: Visual Focus Indicators for AI Elements

As a **user**,
I want **to perceive visual focus indicators on all interactive AI elements**,
So that **I can see which element has keyboard focus**.

**Acceptance Criteria:**

**Given** I am navigating AI features with keyboard
**When** I focus on any interactive AI element (buttons, toggles, inputs, links)
**Then** the element should display a visible focus indicator
**And** the focus indicator should have a minimum 3:1 contrast ratio against the background (NFR-A11Y-003)
**And** the focus indicator should be clearly visible (not just a subtle outline)
**And** the focus indicator should be consistent across all AI features
**And** the focus indicator should work in both light and dark themes
**And** the indicator should not rely solely on color (should include outline or other visual cue) (NFR-A11Y-004)

### Story 8.8: Touch Target Sizing for Mobile AI Features

As a **user on a mobile device**,
I want **all AI feature touch targets to meet minimum size requirements (44x44px)**,
So that **I can easily tap interactive elements without errors**.

**Acceptance Criteria:**

**Given** I am using the application on a mobile device
**When** I interact with AI features (buttons, toggles, suggestions, etc.)
**Then** all interactive elements should have a minimum touch target size of 44x44 pixels (NFR-A11Y-005)
**And** touch targets should have at least 8px spacing between adjacent elements (NFR-A11Y-006)
**And** I should be able to tap targets accurately without zooming
**And** the targets should be large enough for comfortable one-handed use
**And** the sizing should be consistent across all AI features
**And** the targets should work reliably on different mobile device sizes (FR54)

---

## Epic 9: Simplify NoteCard Interface

**Epic Goal:** Simplify the NoteCard interface by reducing the number of visible buttons while preserving all existing content (avatar, images, HTML link previews, labels, dates).

**User Pain Points:**
- Too many buttons in the NoteCard header (multiple action buttons: move to notebook, pin, plus reminder icon and connections badge)
- Interface feels cluttered and takes up visual space
- Actions are scattered across multiple buttons
- Note: Drag handle stays on mobile (not replaced), reminder icon stays if active (not replaced), connections badge stays (not replaced)

**Success Criteria:**
- ✅ Reduce 5 buttons to 1 menu button ("...")
- ✅ All actions remain accessible via the menu
- ✅ Avatar position remains unchanged (bottom-left)
- ✅ Images remain fully visible and clickable
- ✅ HTML link previews remain fully visible and functional
- ✅ Labels remain visible
- ✅ Dates remain visible
- ✅ Memory Echo badges remain visible
- ✅ Interface feels cleaner and less cluttered

**Dependencies:**
- None (standalone epic)

---

### Story 9.1: Create NoteActionMenu Component

As a **developer**,
I want **to create a reusable NoteActionMenu component**,
So that **all note actions are accessible through a single menu interface**.

**Acceptance Criteria:**

**Given** I am implementing the NoteActionMenu component
**When** I create the component
**Then** it should use DropdownMenu from Radix UI
**And** it should display a "..." (MoreHorizontal) icon button
**And** the button should appear on hover (desktop) or be always visible (mobile)
**And** the menu should contain all note actions:
  - Pin/Unpin
  - Move to notebook
  - Set reminder
  - Show connections
  - Color note
  - Share note
  - Archive note
  - Delete note
**And** each menu item should have an appropriate icon
**And** the menu should align to the right (end)
**And** the menu should have proper spacing and styling
**And** the menu should support keyboard navigation
**And** the menu should work in both light and dark themes

**Technical Notes:**
- Component location: `keep-notes/components/note-action-menu.tsx`
- Use `MoreHorizontal` icon from lucide-react
- Use existing DropdownMenu components from `@/components/ui/dropdown-menu`
- Menu width: `w-56` (224px)
- Icons: Pin, FolderOpen, Bell, Link2, Palette, Share2, Archive, Trash2

---

### Story 9.2: Replace Multiple Buttons with Action Menu in NoteCard

As a **user**,
I want **to see a cleaner NoteCard interface with fewer visible buttons**,
So that **the interface is less cluttered and easier to scan**.

**Acceptance Criteria:**

**Given** I am viewing a note card
**When** the note card is displayed
**Then** I should see only 1 menu button ("...") in the top-right corner instead of 5 separate buttons
**And** the drag handle should remain visible on mobile (top-left)
**And** the reminder icon should remain visible if a reminder is active
**And** all other content should remain unchanged:
  - Avatar in bottom-left (position: `bottom-2 left-2`)
  - Images fully visible and clickable
  - HTML link previews fully visible with image, title, description, hostname
  - Labels visible below content
  - Date visible in bottom-right
  - Memory Echo badges visible at top
**When** I hover over the note card (desktop)
**Then** the menu button should become visible (opacity transition)
**When** I click/tap the menu button
**Then** a dropdown menu should appear with all note actions
**And** I should be able to access all actions that were previously in separate buttons
**And** the menu should close after selecting an action

**Technical Notes:**
- Modify `keep-notes/components/note-card.tsx`
- Remove individual button components (lines 289-333 approximately)
- Replace with `<NoteActionMenu />` component
- Keep drag handle for mobile: `md:hidden` (visible only on mobile)
- Keep reminder icon if `note.reminder` is set and in the future
- Menu button should use `opacity-0 group-hover:opacity-100` for desktop hover effect
- Menu button position: `absolute top-2 right-2 z-20`

**Files to Modify:**
- `keep-notes/components/note-card.tsx` - Replace buttons with menu
- `keep-notes/components/note-action-menu.tsx` - New component (created in Story 9.1)

---

### Story 9.3: Ensure Content Preservation After Simplification

As a **user**,
I want **all note content to remain visible and functional after the interface simplification**,
So that **I don't lose any information or functionality**.

**Acceptance Criteria:**

**Given** I have a note with various content types
**When** I view the note card after the simplification
**Then** the avatar should remain in the bottom-left corner (`bottom-2 left-2`)
**And** the avatar should be 24x24px (w-6 h-6)
**And** the avatar should display owner initials
**And** images should remain fully visible (full width)
**And** images should remain clickable to enlarge
**And** HTML link previews should remain fully visible with:
  - Link image (if available)
  - Link title
  - Link description
  - Link hostname
**And** link previews should remain clickable
**And** labels should remain visible below content
**And** labels should maintain their color coding
**And** the date should remain visible in the bottom-right
**And** Memory Echo badges should remain visible at the top
**And** all content should maintain its current styling and behavior

**Technical Notes:**
- No changes to content rendering logic
- Only changes to button/action interface
- Verify all existing content components remain unchanged:
  - `NoteImages` component
  - Link preview rendering (lines 436-461)
  - `LabelBadge` components
  - Date formatting
  - Avatar rendering (lines 492-504)

**Testing:**
- Test with notes containing images
- Test with notes containing HTML link previews
- Test with notes containing multiple labels
- Test with notes with active reminders
- Test with notes with Memory Echo badges
- Verify avatar position on all screen sizes
- Verify all content is clickable and functional

---

### Story 9.4: Mobile Optimization for Action Menu

As a **mobile user**,
I want **to access note actions easily on my mobile device**,
So that **I can manage notes efficiently with touch interactions**.

**Acceptance Criteria:**

**Given** I am using the application on a mobile device (< 768px)
**When** I view a note card
**Then** the menu button should be always visible (not hidden on hover)
**And** the menu button should have a minimum touch target of 44x44px
**When** I tap the menu button
**Then** the dropdown menu should appear
**And** each menu item should have a minimum touch target of 44x44px
**And** the menu should be easy to navigate with touch
**And** the menu should close when I tap outside of it
**And** the menu should close after selecting an action
**And** all actions should work correctly on mobile

**Technical Notes:**
- Menu button: `opacity-100` on mobile (always visible)
- Menu button: `min-h-[44px] min-w-[44px]` for touch target
- Menu items: `min-h-[44px]` for touch targets
- Test on various mobile devices (Galaxy S22 Ultra, iPhone SE, etc.)

---

### Story 9.5: Keyboard Navigation for Action Menu

As a **keyboard user**,
I want **to navigate and use the action menu with keyboard only**,
So that **I can access all note actions without using a mouse**.

**Acceptance Criteria:**

**Given** I am navigating with keyboard only
**When** I focus on a note card
**Then** I should be able to Tab to the menu button
**And** the menu button should have a visible focus indicator
**When** I press Enter or Space on the menu button
**Then** the menu should open
**And** I should be able to navigate menu items with Arrow keys
**And** I should be able to select an action with Enter
**And** I should be able to close the menu with Escape
**And** focus should return to the menu button after closing
**And** all actions should be accessible via keyboard

**Technical Notes:**
- Use Radix UI DropdownMenu which has built-in keyboard support
- Ensure focus indicators are visible (WCAG 2.1 AA)
- Test with screen reader (NVDA, VoiceOver)

---

## Epic 9 Summary

**Stories in Epic 9:**
1. 9.1: Create NoteActionMenu Component
2. 9.2: Replace Multiple Buttons with Action Menu in NoteCard
3. 9.3: Ensure Content Preservation After Simplification
4. 9.4: Mobile Optimization for Action Menu
5. 9.5: Keyboard Navigation for Action Menu

**Total Stories:** 5
**Estimated Complexity:** Medium
**Priority:** Medium (UX improvement)

**Dependencies:**
- Story 9.1 should be done first (foundational component)
- Story 9.2 depends on 9.1
- Stories 9.3, 9.4, 9.5 can be done in parallel after 9.2

**Testing Requirements:**
- ✅ Test on desktop (hover interactions)
- ✅ Test on mobile (touch interactions)
- ✅ Test keyboard navigation
- ✅ Test screen reader compatibility
- ✅ Verify all content remains visible and functional
- ✅ Verify avatar position remains bottom-left
- ✅ Verify images remain visible and clickable
- ✅ Verify HTML link previews remain functional
- ✅ Verify labels remain visible
- ✅ Verify dates remain visible

**Success Metrics:**
- Interface feels less cluttered (user feedback)
- All actions remain accessible
- Zero regression in content visibility
- Zero regression in functionality
- Improved accessibility (keyboard navigation)

---

## Epic 10: Design System Standardization

**Epic Goal:** Implement a consistent design system across the entire application to improve visual hierarchy, usability, and maintainability.

**User Pain Points:**
- Inconsistent spacing across components
- Inconsistent colors and typography
- Inconsistent border radius and shadows
- No clear design guidelines for developers
- Visual hierarchy is unclear in some areas

**Success Criteria:**
- ✅ Consistent 4px base unit spacing scale implemented
- ✅ Standardized color palette with semantic colors
- ✅ Consistent typography scale (headings, body, small)
- ✅ Standardized border radius values
- ✅ Standardized shadow/elevation levels
- ✅ All components follow design system
- ✅ Design system documentation created
- ✅ Improved visual hierarchy throughout app

**Dependencies:**
- None (standalone epic)

---

### Story 10.1: Implement Spacing Scale (4px Base Unit)

As a **developer**,
I want **a consistent spacing scale based on 4px units**,
So that **all components have consistent padding, margins, and gaps**.

**Acceptance Criteria:**

**Given** I am implementing or updating a component
**When** I apply spacing
**Then** I should use the 4px base unit scale:
  - `p-1` = 4px
  - `p-2` = 8px
  - `p-3` = 12px
  - `p-4` = 16px
  - `p-6` = 24px
**And** all cards should use `p-4` (16px) for padding
**And** all gaps between elements should follow the scale
**And** all margins should follow the scale
**And** the spacing should be consistent across similar components

**Technical Notes:**
- Update Tailwind config if needed
- Audit all components for spacing inconsistencies
- Create spacing guidelines document
- Update components: NoteCard, Card, Input, Badge, Button, Header

---

### Story 10.2: Standardize Color Palette

As a **user**,
I want **consistent colors throughout the application**,
So that **the interface feels cohesive and professional**.

**Acceptance Criteria:**

**Given** I am viewing the application
**When** I navigate between screens
**Then** colors should be consistent:
  - Primary colors (brand, actions)
  - Secondary colors (backgrounds, borders)
  - Accent colors (highlights, warnings)
  - Text colors (primary, secondary, disabled)
  - Status colors (success, error, warning, info)
**And** semantic colors should be used (not hardcoded hex values)
**And** dark mode should have proper contrast
**And** all interactive elements should have consistent hover states

**Technical Notes:**
- Use CSS variables for semantic colors
- Define color palette in Tailwind config
- Ensure WCAG 2.1 AA contrast ratios
- Update all components to use semantic colors

---

### Story 10.3: Standardize Typography Scale

As a **user**,
I want **consistent typography throughout the application**,
So that **text is readable and hierarchy is clear**.

**Acceptance Criteria:**

**Given** I am viewing text in the application
**When** I read content
**Then** typography should follow a consistent scale:
  - Headings: Consistent font sizes and weights
  - Body text: Consistent font size and line height
  - Small text: Consistent font size for labels, captions
**And** line heights should be appropriate for readability
**And** font weights should be consistent (bold, semibold, regular)
**And** text colors should follow the color palette

**Technical Notes:**
- Define typography scale in Tailwind config
- Update all headings (h1-h6)
- Update body text components
- Update small text (labels, captions, dates)

---

### Story 10.4: Standardize Border Radius and Shadows

As a **developer**,
I want **consistent border radius and shadow values**,
So that **components have a cohesive visual style**.

**Acceptance Criteria:**

**Given** I am implementing a component
**When** I apply border radius or shadows
**Then** I should use standardized values:
  - Border radius: `rounded-sm` (2px), `rounded` (4px), `rounded-md` (6px), `rounded-lg` (8px)
  - Shadows: `shadow-sm`, `shadow`, `shadow-md`, `shadow-lg`
**And** similar components should use the same values
**And** elevation should be consistent (cards, modals, dropdowns)
**And** hover states should have consistent elevation changes

**Technical Notes:**
- Define shadow scale in Tailwind config
- Update all cards to use consistent border radius
- Update all modals and dropdowns
- Update hover states

---

## Epic 10 Summary

**Stories in Epic 10:**
1. 10.1: Implement Spacing Scale (4px Base Unit)
2. 10.2: Standardize Color Palette
3. 10.3: Standardize Typography Scale
4. 10.4: Standardize Border Radius and Shadows

**Total Stories:** 4
**Estimated Complexity:** Medium
**Priority:** Medium (UX improvement)

---

## Epic 11: Settings Interface Redesign

**Epic Goal:** Redesign the settings interface to be more intuitive, organized, and user-friendly.

**User Pain Points:**
- Settings are hard to find
- Settings are not well organized
- No clear sections or navigation
- Settings descriptions are unclear
- Mobile settings experience is poor

**Success Criteria:**
- ✅ Settings organized in clear sections
- ✅ Sidebar navigation for settings sections
- ✅ Search/filter functionality for settings
- ✅ Clear labels and descriptions for each setting
- ✅ Immediate visual feedback on save
- ✅ Responsive design for mobile
- ✅ Settings persist correctly

**Dependencies:**
- Epic 10 (Design System) recommended but not required

---

### Story 11.1: Organize Settings into Clear Sections

As a **user**,
I want **settings organized into clear, logical sections**,
So that **I can easily find the settings I need**.

**Acceptance Criteria:**

**Given** I am viewing the settings page
**When** I navigate settings
**Then** settings should be organized into sections:
  - General (theme, language, etc.)
  - AI Settings (provider, features, etc.)
  - Account (profile, security, etc.)
  - Data Management (export, sync, etc.)
  - About & Help
**And** each section should have a clear title
**And** settings should be grouped logically within sections
**And** I should be able to navigate between sections easily

**Technical Notes:**
- Create settings sections component
- Organize existing settings into sections
- Add section navigation (sidebar or tabs)

---

### Story 11.2: Add Settings Search and Filter

As a **user**,
I want **to search and filter settings**,
So that **I can quickly find specific settings**.

**Acceptance Criteria:**

**Given** I am on the settings page
**When** I type in the search box
**Then** settings should be filtered in real-time
**And** matching settings should be highlighted
**And** sections containing matches should be expanded
**And** I should see a count of matching settings
**And** the search should work across all sections

**Technical Notes:**
- Add search input component
- Implement filtering logic
- Highlight matching text
- Auto-expand sections with matches

---

### Story 11.3: Improve Settings Descriptions and Labels

As a **user**,
I want **clear descriptions for each setting**,
So that **I understand what each setting does**.

**Acceptance Criteria:**

**Given** I am viewing a setting
**When** I read the setting
**Then** the label should be clear and descriptive
**And** there should be a description explaining what the setting does
**And** the description should explain the impact of changing the setting
**And** tooltips or help icons should be available for complex settings
**And** examples should be provided where helpful

**Technical Notes:**
- Add description text to all settings
- Add tooltip/help icon component
- Update all setting labels for clarity
- Add examples where needed

---

### Story 11.4: Improve Mobile Settings Experience

As a **mobile user**,
I want **an optimized settings experience on mobile**,
So that **I can configure the app easily on my device**.

**Acceptance Criteria:**

**Given** I am using the app on mobile (< 768px)
**When** I access settings
**Then** the layout should be optimized for mobile
**And** touch targets should be minimum 44x44px
**And** sections should be collapsible/expandable
**And** navigation should be easy (no horizontal scroll)
**And** settings should be easy to toggle and configure

**Technical Notes:**
- Create mobile-optimized settings layout
- Use collapsible sections on mobile
- Ensure touch targets meet minimum size
- Test on various mobile devices

---

## Epic 11 Summary

**Stories in Epic 11:**
1. 11.1: Organize Settings into Clear Sections
2. 11.2: Add Settings Search and Filter
3. 11.3: Improve Settings Descriptions and Labels
4. 11.4: Improve Mobile Settings Experience

**Total Stories:** 4
**Estimated Complexity:** Medium
**Priority:** Medium (UX improvement)

---

## Epic 12: Mobile Experience Optimization

**Epic Goal:** Optimize the mobile experience to ensure the interface works perfectly on mobile devices without changing the desktop experience.

**User Pain Points:**
- Interface overflows on mobile devices
- Note cards too complex for mobile
- Masonry grid not suitable for small screens
- Touch targets too small
- No mobile-specific UX patterns

**Success Criteria:**
- ✅ No horizontal/vertical overflow on mobile
- ✅ Simplified note cards for mobile
- ✅ Mobile-first layouts
- ✅ Touch targets minimum 44x44px
- ✅ Smooth 60fps animations
- ✅ Desktop interface unchanged
- ✅ Tested on various mobile devices

**Dependencies:**
- Epic 9 (NoteCard simplification) recommended
- Epic 10 (Design System) recommended

---

### Story 12.1: Mobile Note Cards Simplification

As a **mobile user**,
I want **simple, compact note cards on mobile**,
So that **I can see more notes and scan quickly**.

**Acceptance Criteria:**

**Given** I am viewing notes on mobile (< 768px)
**When** notes are displayed
**Then** notes should be in a vertical list (not masonry)
**And** cards should show title + 2-3 lines preview only
**And** badges should be minimized (pin icon, label count)
**And** image thumbnails should be hidden on mobile
**And** touch targets should be minimum 44x44px
**And** cards should be 100% width

**Technical Notes:**
- Create mobile variant of NoteCard
- Replace masonry grid with list on mobile
- Hide image thumbnails on mobile
- Minimize badges and indicators

---

### Story 12.2: Mobile-First Layout Optimization

As a **mobile user**,
I want **a layout optimized for mobile screens**,
So that **the interface fits perfectly on my device**.

**Acceptance Criteria:**

**Given** I am using the app on mobile
**When** I view the interface
**Then** there should be no horizontal overflow
**And** there should be no vertical overflow
**And** content should be properly sized for mobile
**And** spacing should be appropriate for touch
**And** the layout should adapt to different screen sizes

**Technical Notes:**
- Implement mobile-first breakpoints
- Fix overflow issues
- Optimize spacing for mobile
- Test on Galaxy S22 Ultra, iPhone SE, etc.

---

### Story 12.3: Mobile Touch Interactions

As a **mobile user**,
I want **touch-friendly interactions**,
So that **I can use the app easily with my fingers**.

**Acceptance Criteria:**

**Given** I am using the app on mobile
**When** I interact with elements
**Then** all touch targets should be minimum 44x44px
**And** swipe gestures should work (swipe to delete, etc.)
**And** long-press should show context menu
**And** tap interactions should be responsive
**And** there should be no accidental taps

**Technical Notes:**
- Ensure all buttons/links are 44x44px minimum
- Implement swipe gesture handlers
- Add long-press handlers
- Test touch interactions thoroughly

---

### Story 12.4: Mobile Performance Optimization

As a **mobile user**,
I want **smooth, fast performance on mobile**,
So that **the app feels responsive and fluid**.

**Acceptance Criteria:**

**Given** I am using the app on mobile
**When** I interact with the interface
**Then** animations should run at 60fps
**And** scrolling should be smooth
**And** interactions should feel instant (< 100ms)
**And** the app should not lag or freeze
**And** battery usage should be optimized

**Technical Notes:**
- Optimize animations (use GPU acceleration)
- Implement lazy loading
- Reduce re-renders
- Optimize images for mobile
- Use skeleton loading states

---

## Epic 12 Summary

**Stories in Epic 12:**
1. 12.1: Mobile Note Cards Simplification
2. 12.2: Mobile-First Layout Optimization
3. 12.3: Mobile Touch Interactions
4. 12.4: Mobile Performance Optimization

**Total Stories:** 4
**Estimated Complexity:** High
**Priority:** High (critical for mobile users)

**Dependencies:**
- Story 12.1 should be done first (foundational)
- Story 12.2 depends on 12.1
- Stories 12.3 and 12.4 can be done in parallel

---

## Epic 13: Desktop Design Refactor

The desktop interface will be redesigned based on the reference HTML file `code.html` to improve visual hierarchy, enhance usability, and create a modern, cohesive design. The refactor will include improved notebook view, better navigation, cleaner typography, and enhanced interactions while maintaining all existing functionality.

**Design Goals:**
- Modern visual design inspired by `code.html`
- Improved information architecture
- Enhanced usability and discoverability
- Better keyboard navigation
- Consistent with Design System (Epic 10)

**Key Components to Refactor:**
- Notebook main page (sidebar + content area)
- Note list view
- Note editor interface
- Search and filtering
- Settings panels
- Admin dashboard (if applicable)

**Success Criteria:**
- ✅ Visual design matches reference HTML `code.html`
- ✅ Improved usability (reduced clicks, better organization)
- ✅ Consistent spacing, typography, and colors
- ✅ Smooth animations and transitions
- ✅ Enhanced keyboard navigation
- ✅ Responsive design for desktop (1024px+)
- ✅ All existing functionality preserved

**Dependencies:**
- Epic 10 (Design System) recommended as foundation

---

### Story 13.1: Refactor Notebook Main Page Layout

As a **desktop user**,
I want **a clean, modern notebook page layout with improved visual hierarchy**,
So that **I can navigate and find my notes easily**.

**Acceptance Criteria:**

**Given** I am using the app on desktop (1024px+)
**When** I view the notebook main page
**Then** I should see a clean layout with sidebar on the left and content area on the right
**And** the sidebar should show: notebook list, filters, and actions
**And** the content area should show: note cards in a responsive grid
**And** the spacing should be consistent and visually pleasing
**And** the typography should be clear and readable
**And** the design should match the reference HTML `code.html`

**Technical Notes:**
- Implement flexbox or grid layout for main page
- Use Design System components (Card, Button, Badge)
- Consistent spacing (4px base unit)
- Clear visual hierarchy (headings, subheadings, labels)
- Responsive design for different desktop sizes (1024px, 1440px, 1920px)

---

### Story 13.2: Refactor Note Cards Display

As a **desktop user**,
I want **modern, clean note cards with improved visual design**,
So that **I can quickly scan and identify notes**.

**Acceptance Criteria:**

**Given** I am viewing notes on desktop
**When** I look at note cards
**Then** each card should show: title, preview, labels, date, and metadata
**And** cards should have consistent sizing and spacing
**And** cards should have hover states (slight elevation or color change)
**And** cards should support pinned state with visual indicator
**And** cards should display image thumbnails when present
**And** the grid layout should be responsive (adjust columns based on screen width)

**Technical Notes:**
- Use Card component from Design System
- Implement masonry or responsive grid layout
- Add hover animations (elevation or scale)
- Consistent card padding and border radius
- Optimize image thumbnails

---

### Story 13.3: Refactor Note Editor Interface

As a **desktop user**,
I want **a clean, modern note editor with improved toolbar and formatting**,
So that **I can write and edit notes efficiently**.

**Acceptance Criteria:**

**Given** I am editing a note on desktop
**When** I look at the editor interface
**Then** I should see a clean toolbar with formatting options
**And** the toolbar should be positioned at the top of the editor
**And** the editor should support: bold, italic, underline, lists, links, images
**And** the toolbar should have clear icons or labels
**And** the editor should have a clean, distraction-free writing area
**And** there should be keyboard shortcuts for common actions

**Technical Notes:**
- Use Button and Input components from Design System
- Clear toolbar with grouped actions
- Keyboard shortcuts (Ctrl+B for bold, Ctrl+I for italic, etc.)
- Clean typography for editor content
- Responsive editor width

---

### Story 13.4: Refactor Search and Filtering Interface

As a **desktop user**,
I want **an improved search and filtering interface with clear visual design**,
So that **I can quickly find specific notes**.

**Acceptance Criteria:**

**Given** I am searching for notes on desktop
**When** I interact with the search interface
**Then** I should see a clear search input with placeholder text
**And** I should see filtering options (by label, date, notebook, etc.)
**And** I should see search results with visual indicators (exact vs semantic matches)
**And** the search should be responsive (update as I type)
**And** I should see clear "No results" message when no matches found
**And** I should be able to clear the search easily

**Technical Notes:**
- Use Input component from Design System
- Clear search input with focus state
- Filter chips or dropdowns
- Real-time search (debounced)
- Visual indicators for match types
- Clear feedback states

---

### Story 13.5: Refactor Settings Panels

As a **desktop user**,
I want **clean, organized settings panels with improved UX**,
So that **I can configure the application easily**.

**Acceptance Criteria:**

**Given** I am viewing settings on desktop
**When** I look at the settings interface
**Then** I should see clear sections for different settings categories
**And** each section should have a heading and description
**And** controls (toggles, dropdowns, inputs) should be clearly labeled
**And** I should see save/reset buttons for each section
**And** the layout should be organized and easy to scan
**And** changes should be saved automatically or with clear confirmation

**Technical Notes:**
- Organized layout with clear sections
- Consistent spacing and grouping
- Clear labels and descriptions
- Appropriate input types (toggle, select, text)
- Save/reset functionality
- Feedback for successful changes

---

### Story 13.6: Improve Navigation and Breadcrumbs

As a **desktop user**,
I want **clear navigation with breadcrumbs and visual hierarchy**,
So that **I always know where I am in the application**.

**Acceptance Criteria:**

**Given** I am navigating the application on desktop
**When** I move between pages
**Then** I should see breadcrumbs showing my current location
**And** I should be able to click breadcrumbs to go back
**And** the active page should be visually highlighted
**And** navigation should be consistent across all pages
**And** navigation should support keyboard shortcuts

**Technical Notes:**
- Breadcrumb component with links
- Visual indicator for active page
- Consistent navigation across pages
- Keyboard navigation support
- Responsive design

---

### Story 13.7: Enhance Animations and Micro-interactions

As a **desktop user**,
I want **smooth animations and micro-interactions throughout the interface**,
So that **the application feels polished and responsive**.

**Acceptance Criteria:**

**Given** I am interacting with the application on desktop
**When** I perform actions (hover, click, focus)
**Then** I should see smooth transitions on all interactive elements
**And** hover states should be clear and consistent
**And** focus states should be visible for accessibility
**And** animations should be smooth (60fps)
**And** micro-interactions should provide visual feedback
**And** animations should not be distracting or too slow

**Technical Notes:**
- CSS transitions for hover/focus states
- Consistent transition duration (150-200ms)
- Use GPU acceleration for animations
- Subtle, purposeful animations
- Accessibility considerations (respect prefers-reduced-motion)

---

### Story 13.8: Refactor Admin Dashboard (if applicable)

As an **administrator**,
I want **a modern, clean admin dashboard with improved visual design**,
So that **I can manage the application effectively**.

**Acceptance Criteria:**

**Given** I am accessing the admin dashboard on desktop
**When** I view the dashboard
**Then** I should see a clean layout with: metrics, charts, and controls
**And** metrics should be clearly displayed with labels and values
**And** charts should be responsive and interactive
**And** controls (filters, actions) should be clearly organized
**And** the design should match the rest of the application
**And** I should be able to view metrics for different time periods

**Technical Notes:**
- Grid layout for metrics
- Responsive charts
- Clear metric cards
- Consistent spacing and typography
- Filtering and controls
- Use Design System components

---

## Epic 14: Admin & Profil Redesign

The admin dashboard and user profile pages will be redesigned to improve usability, enhance visual design, and create a cohesive experience. The redesign will focus on better organization, clearer information architecture, and improved interactions.

**Design Goals:**
- Improved usability and discoverability
- Clear information architecture
- Enhanced visual design
- Better error handling and feedback
- Consistent with Design System (Epic 10)

**Key Components to Redesign:**
- Admin dashboard layout
- User profile settings
- AI settings panel
- Admin metrics and controls
- User account management

**Success Criteria:**
- ✅ Improved usability (reduced clicks, better organization)
- ✅ Clear information architecture
- ✅ Enhanced visual design
- ✅ Better error handling and feedback
- ✅ Responsive design for desktop (1024px+)
- ✅ All existing functionality preserved

**Dependencies:**
- Epic 10 (Design System) recommended as foundation
- Epic 13 (Desktop Design Refactor) for consistency

---

### Story 14.1: Redesign Admin Dashboard Layout

As an **administrator**,
I want **a clean, modern admin dashboard layout with improved organization**,
So that **I can manage the application efficiently**.

**Acceptance Criteria:**

**Given** I am accessing the admin dashboard on desktop
**When** I view the dashboard
**Then** I should see a sidebar navigation with: Dashboard, Users, AI Management, Settings
**And** I should see a main content area with: metrics, charts, and tables
**And** the layout should be responsive (adapt to different screen sizes)
**And** I should be able to navigate between sections easily
**And** the active section should be visually highlighted

**Technical Notes:**
- Sidebar navigation with links
- Responsive main content area
- Consistent spacing and typography
- Visual indicator for active section
- Use Design System components

---

### Story 14.2: Redesign Admin Metrics Display

As an **administrator**,
I want **clear, readable metrics with improved visual design**,
So that **I can understand application performance at a glance**.

**Acceptance Criteria:**

**Given** I am viewing the admin dashboard
**When** I look at the metrics
**Then** I should see: total users, active users, total notes, AI usage, etc.
**And** each metric should be displayed in a card with label and value
**And** I should be able to filter metrics by time period (today, week, month, custom)
**And** I should see trend indicators (up/down arrows with percentages)
**And** the metrics should be easy to scan and understand
**And** I should be able to click a metric to see more details

**Technical Notes:**
- Metric cards with consistent design
- Time period filters
- Trend indicators (color-coded: green for up, red for down)
- Clickable metrics for details
- Use Card component from Design System

---

### Story 14.3: Redesign AI Settings Panel

As a **user**,
I want **a clean, organized AI settings panel with improved UX**,
So that **I can configure AI features easily**.

**Acceptance Criteria:**

**Given** I am viewing AI settings on desktop
**When** I look at the settings
**Then** I should see clear sections for: AI Provider, Feature Toggles, Advanced Options
**And** I should be able to select AI provider (Auto, Ollama, OpenAI)
**And** I should be able to toggle individual AI features (Title Suggestions, Semantic Search, etc.)
**And** I should see descriptions for each setting
**And** I should be able to save changes with one click
**And** I should see clear feedback when settings are saved

**Technical Notes:**
- Organized sections with headings
- Toggle switches for feature toggles
- Dropdown for AI provider selection
- Clear descriptions and labels
- Save functionality with feedback
- Use Design System components (Toggle, Select, Button)

---

### Story 14.4: Redesign User Profile Settings

As a **user**,
I want **a clean, organized profile settings page with improved UX**,
So that **I can manage my account and preferences easily**.

**Acceptance Criteria:**

**Given** I am viewing my profile settings on desktop
**When** I look at the settings
**Then** I should see sections for: Personal Info, Account, Preferences, Notifications
**And** I should be able to edit my personal information (name, email, etc.)
**And** I should be able to change my password
**And** I should be able to configure notifications
**And** I should be able to set theme preferences (Light, Dark, Midnight, Sepia)
**And** I should see clear feedback when settings are saved

**Technical Notes:**
- Organized sections with headings
- Input fields for text data
- Password change flow
- Theme selection
- Notification settings
- Save functionality with feedback

---

### Story 14.5: Redesign Admin User Management

As an **administrator**,
I want **an improved user management interface with better organization**,
So that **I can manage users efficiently**.

**Acceptance Criteria:**

**Given** I am managing users in the admin dashboard
**When** I view the user management interface
**Then** I should see a table or list of all users
**And** I should be able to search and filter users
**And** I should be able to view user details
**And** I should be able to edit user settings
**And** I should be able to suspend or delete users
**And** the interface should be clean and organized

**Technical Notes:**
- Table or list view of users
- Search and filter functionality
- User detail modal or page
- Edit user settings
- Suspend/delete user actions
- Use Design System components (Table, Button, Modal)

---

### Story 14.6: Redesign Admin AI Management

As an **administrator**,
I want **an improved AI management interface with better visualization**,
So that **I can monitor and configure AI usage effectively**.

**Acceptance Criteria:**

**Given** I am managing AI settings in the admin dashboard
**When** I view the AI management interface
**Then** I should see metrics: total AI requests, average response time, costs, etc.
**And** I should be able to configure default AI settings for all users
**And** I should be able to set rate limits per user
**And** I should be able to view AI usage per user
**And** I should see charts and visualizations of usage trends
**And** the interface should be clear and organized

**Technical Notes:**
- Metrics display with charts
- Default AI settings configuration
- Rate limit configuration
- Per-user usage view
- Responsive charts and tables
- Use Design System components

---

### Story 14.7: Improve Error Handling and Feedback

As a **user or administrator**,
I want **clear error messages and feedback throughout the admin/profile pages**,
So that **I understand what went wrong and how to fix it**.

**Acceptance Criteria:**

**Given** I am using admin or profile pages
**When** an error occurs
**Then** I should see a clear error message explaining what went wrong
**And** I should see suggestions on how to fix the error
**And** the error message should be visually distinct (red color, icon)
**And** I should be able to dismiss the error message
**And** I should see success messages when actions complete successfully
**And** loading states should be clear and informative

**Technical Notes:**
- Error message component with styling
- Success message component with styling
- Loading states (spinners, skeletons)
- Dismiss functionality for messages
- Clear, actionable error text
- Use Design System components

---

### Story 14.8: Add Keyboard Navigation Support

As a **user or administrator**,
I want **full keyboard navigation support in admin/profile pages**,
So that **I can use the interface without a mouse**.

**Acceptance Criteria:**

**Given** I am using admin or profile pages
**When** I navigate with the keyboard
**Then** I should be able to Tab through all interactive elements
**Then** I should see clear focus indicators on the focused element
**Then** I should be able to activate buttons with Enter/Space
**Then** I should be able to close modals with ESC
**Then** I should be able to navigate tables with arrow keys
**Then** I should be able to select options with arrow keys and Enter

**Technical Notes:**
- Focus visible styles
- Keyboard event handlers
- Tab order should be logical
- ESC key for closing modals
- Arrow key navigation for tables
- Use Design System focus states

---

### Story 14.9: Implement Dark Mode Support

As a **user or administrator**,
I want **dark mode support in admin/profile pages**,
So that **I can use the application comfortably in different lighting**.

**Acceptance Criteria:**

**Given** I am using admin or profile pages
**When** I toggle dark mode
**Then** the entire interface should switch to dark colors
**And** the contrast should remain readable
**And** all colors should respect the dark theme palette
**And** I should be able to toggle between light and dark mode
**And** the theme should persist across sessions

**Technical Notes:**
- CSS variables for theme colors
- Theme toggle component
- Persist theme preference (localStorage or database)
- Test contrast ratios in both themes
- Use Design System theme support

---

### Story 14.10: Improve Responsive Design for Admin/Profile

As a **user or administrator**,
I want **responsive design that works well on different screen sizes**,
So that **I can use the application on desktop and tablet**.

**Acceptance Criteria:**

**Given** I am using admin or profile pages on desktop (1024px+) or tablet (640px-1023px)
**When** I resize the window
**Then** the layout should adapt to the screen size
**And** I should not see horizontal overflow
**And** the sidebar should collapse on smaller screens
**And** the content should remain readable and accessible
**And** touch targets should be minimum 44x44px on tablet

**Technical Notes:**
- Responsive breakpoints (640px, 768px, 1024px)
- Flexbox or grid layouts
- Collapsible sidebar on smaller screens
- Touch targets (44x44px minimum)
- Test on various screen sizes

---

### Story 14.11: Add Loading States and Skeletons

As a **user or administrator**,
I want **clear loading states and skeleton screens**,
So that **I know the application is working**.

**Acceptance Criteria:**

**Given** I am loading data in admin or profile pages
**When** the data is loading
**Then** I should see a skeleton screen or spinner
**And** the skeleton should match the actual layout
**And** I should see the actual data when loading completes
**And** I should see an error message if loading fails
**And** the loading experience should be smooth and not jarring

**Technical Notes:**
- Skeleton component with shimmer effect
- Spinner component for async operations
- Error states with retry option
- Smooth transitions between loading and loaded
- Match skeleton layout to actual content

---

### Story 14.12: Add Accessibility Improvements

As a **user with disabilities**,
I want **full accessibility support in admin/profile pages**,
So that **I can use the application effectively**.

**Acceptance Criteria:**

**Given** I am using admin or profile pages with assistive technology
**When** I navigate or interact with the interface
**Then** I should be able to navigate using only a keyboard
**Then** I should hear screen reader announcements for important actions
**Then** I should see high contrast colors (WCAG 2.1 AA)
**Then** I should be able to zoom in up to 200% without breaking layout
**Then** I should be able to use touch targets minimum 44x44px
**Then** all interactive elements should have proper ARIA labels

**Technical Notes:**
- Keyboard navigation (Tab, Enter, ESC, arrows)
- ARIA labels and roles
- Color contrast ratios (4.5:1 for text, 3:1 for UI)
- Zoom support (up to 200%)
- Touch targets (44x44px minimum)
- Screen reader testing

---

## Epic 15: Mobile UX Overhaul

The mobile experience will be completely redesigned based on the reference HTML file `code_mobile.html` to improve usability, enhance touch interactions, and create a modern, cohesive mobile-first design. The overhaul will include simplified layouts, larger touch targets, gesture support, and mobile-specific UX patterns.

**Design Goals:**
- Mobile-first design approach
- Enhanced touch interactions
- Simplified information architecture
- Improved performance on mobile devices
- Consistent with Design System (Epic 10)

**Key Components to Overhaul:**
- Mobile navigation (hamburger menu, bottom nav, etc.)
- Mobile note cards (simplified, larger touch targets)
- Mobile editor (simplified toolbar, better mobile input)
- Mobile search and filtering
- Mobile settings
- Gesture support (swipe, long-press, pull-to-refresh)

**Success Criteria:**
- ✅ Design matches reference HTML `code_mobile.html`
- ✅ Touch targets minimum 44x44px
- ✅ No horizontal/vertical overflow
- ✅ Smooth 60fps animations
- ✅ Gesture support (swipe, long-press, pull-to-refresh)
- ✅ Improved performance on mobile
- ✅ All existing functionality preserved

**Dependencies:**
- Epic 10 (Design System) recommended as foundation
- Epic 12 (Mobile Experience) for mobile patterns

---

### Story 15.1: Redesign Mobile Navigation

As a **mobile user**,
I want **a clear, intuitive mobile navigation system**,
So that **I can navigate the app easily on my phone**.

**Acceptance Criteria:**

**Given** I am using the app on mobile (< 768px)
**When** I view the navigation
**Then** I should see a hamburger menu icon in the top-left or bottom navigation bar
**When** I tap the hamburger menu or bottom nav
**Then** I should see a slide-out menu with: Notebooks, Settings, Profile, etc.
**And** the menu should have smooth animation
**And** I should be able to close the menu by tapping outside or tapping the close button
**And** the active page should be visually highlighted in the navigation

**Technical Notes:**
- Hamburger menu or bottom navigation
- Slide-out menu with smooth animation
- Touch-friendly (44x44px minimum touch targets)
- Close button or tap-outside to close
- Visual indicator for active page
- Use Design System components

---

### Story 15.2: Redesign Mobile Note Cards

As a **mobile user**,
I want **simplified, large note cards with better touch targets**,
So that **I can easily interact with notes on my phone**.

**Acceptance Criteria:**

**Given** I am viewing notes on mobile (< 768px)
**When** I look at note cards
**Then** I should see simplified cards showing: title, 2-3 lines preview, date
**And** cards should be 100% width (not in masonry grid)
**And** cards should be in a vertical list
**And** touch targets should be minimum 44x44px
**And** I should be able to swipe left to delete or right to pin
**And** I should be able to long-press to see more options

**Technical Notes:**
- Simplified card design
- Vertical list layout (not masonry)
- Touch targets 44x44px minimum
- Swipe gestures (left: delete, right: pin)
- Long-press context menu
- Use Design System Card component

---

### Story 15.3: Redesign Mobile Note Editor

As a **mobile user**,
I want **a simplified note editor with mobile-friendly toolbar**,
So that **I can write and edit notes easily on my phone**.

**Acceptance Criteria:**

**Given** I am editing a note on mobile
**When** I view the editor
**Then** I should see a clean toolbar at the bottom of the screen
**And** the toolbar should show: bold, italic, list, link, image buttons
**And** the toolbar should have large, touch-friendly buttons (44x44px minimum)
**And** I should be able to tap buttons to apply formatting
**And** the editor should use the full screen height
**And** I should be able to dismiss the keyboard by tapping outside

**Technical Notes:**
- Bottom toolbar for easy thumb access
- Large touch targets (44x44px)
- Full-screen editor
- Keyboard handling (dismiss on tap outside)
- Use Design System Button component

---

### Story 15.4: Redesign Mobile Search and Filtering

As a **mobile user**,
I want **a simplified search interface with mobile-friendly filters**,
So that **I can quickly find notes on my phone**.

**Acceptance Criteria:**

**Given** I am searching for notes on mobile
**When** I view the search interface
**Then** I should see a large search input at the top of the screen
**And** I should see filter chips below the search input
**And** I should be able to tap filter chips to toggle filters
**And** I should see search results in a vertical list
**And** I should be able to tap a result to open the note
**And** I should see a clear "No results" message when no matches found

**Technical Notes:**
- Large search input (easy to tap)
- Filter chips (pill-shaped buttons)
- Vertical list of results
- Touch targets 44x44px minimum
- Real-time search (debounced)
- Use Design System Input and Button components

---

### Story 15.5: Implement Gesture Support

As a **mobile user**,
I want **gesture support for common actions**,
So that **I can interact with the app efficiently**.

**Acceptance Criteria:**

**Given** I am using the app on mobile
**When** I perform gestures
**Then** I should be able to swipe left on a note card to delete it
**And** I should be able to swipe right on a note card to pin it
**And** I should be able to long-press on a note to see context menu
**And** I should be able to pull down on a list to refresh
**And** gestures should be smooth and responsive
**And** I should see visual feedback for gestures

**Technical Notes:**
- Swipe left: delete
- Swipe right: pin
- Long-press: context menu
- Pull-to-refresh
- Touch event handlers
- Visual feedback (animations, colors)

---

### Story 15.6: Redesign Mobile Settings

As a **mobile user**,
I want **a clean, organized mobile settings interface**,
So that **I can configure the app easily on my phone**.

**Acceptance Criteria:**

**Given** I am viewing settings on mobile
**When** I look at the settings
**Then** I should see organized sections with: Personal Info, Account, Preferences, Notifications
**And** I should be able to tap a section to expand it
**And** I should see clear labels and descriptions
**And** I should be able to toggle switches or tap buttons to change settings
**And** I should see clear feedback when settings are saved
**And** touch targets should be minimum 44x44px

**Technical Notes:**
- Organized sections with expandable accordions
- Toggle switches and buttons
- Clear labels and descriptions
- Touch targets 44x44px minimum
- Save functionality with feedback
- Use Design System components

---

### Story 15.7: Optimize Mobile Performance

As a **mobile user**,
I want **smooth, fast performance on mobile devices**,
So that **the app feels responsive and fluid**.

**Acceptance Criteria:**

**Given** I am using the app on mobile
**When** I interact with the app
**Then** animations should run at 60fps
**And** scrolling should be smooth
**And** interactions should feel instant (< 100ms)
**And** the app should not lag or freeze
**And** battery usage should be optimized
**And** data usage should be optimized (lazy loading, etc.)

**Technical Notes:**
- GPU acceleration for animations
- Lazy loading for images and content
- Reduce re-renders
- Optimize images for mobile
- Use skeleton loading states
- Battery and data optimization

---

### Story 15.8: Implement Pull-to-Refresh

As a **mobile user**,
I want **pull-to-refresh on lists and content pages**,
So that **I can easily refresh content**.

**Acceptance Criteria:**

**Given** I am viewing a list or content page on mobile
**When** I pull down on the list
**Then** I should see a refresh indicator (spinner or animation)
**When** I release the pull
**Then** the content should refresh
**And** I should see updated content
**And** the pull should have smooth animation
**And** the pull should trigger only when intentional (not accidental)

**Technical Notes:**
- Pull gesture detection
- Refresh indicator (spinner or animation)
- Refresh content on release
- Smooth animation
- Prevent accidental triggers (threshold)
- Test on various mobile devices

---

### Story 15.9: Implement Skeleton Loading States on Mobile

As a **mobile user**,
I want **skeleton loading states while content is loading**,
So that **I know the app is working**.

**Acceptance Criteria:**

**Given** I am loading content on mobile
**When** the content is loading
**Then** I should see skeleton screens matching the actual layout
**And** the skeleton should have a shimmer effect
**And** I should see the actual content when loading completes
**And** the transition should be smooth
**And** I should see an error message if loading fails

**Technical Notes:**
- Skeleton component with shimmer effect
- Match skeleton layout to actual content
- Smooth transitions
- Error states with retry option
- Use Design System skeleton styles

---

### Story 15.10: Improve Mobile Accessibility

As a **mobile user with disabilities**,
I want **full accessibility support on mobile**,
So that **I can use the app effectively with assistive technology**.

**Acceptance Criteria:**

**Given** I am using the app on mobile with assistive technology
**When** I navigate or interact with the app
**Then** I should be able to navigate using only touch gestures
**Then** I should hear screen reader announcements for important actions
**Then** I should see high contrast colors (WCAG 2.1 AA)
**Then** I should be able to zoom in up to 200% without breaking layout
**Then** I should be able to use touch targets minimum 44x44px
**Then** all interactive elements should have proper ARIA labels

**Technical Notes:**
- Touch gesture support
- Screen reader announcements (iOS VoiceOver, Android TalkBack)
- Color contrast ratios (4.5:1 for text, 3:1 for UI)
- Zoom support (up to 200%)
- Touch targets (44x44px minimum)
- ARIA labels and roles
- Test on iOS and Android devices

---

## Epic 16: Playwright Test Suite

A comprehensive Playwright test suite will be created to test all modals, popups, and critical workflows. This epic ensures reliability, catches regressions, and provides confidence in the codebase. Tests will be automated, maintainable, and cover both happy paths and edge cases.

**Testing Goals:**
- Test all modals and popups (13+ components identified)
- Test critical user workflows
- Ensure accessibility compliance
- Test responsive design (mobile, tablet, desktop)
- Test keyboard navigation
- Test cross-browser compatibility (Chrome, Firefox, Safari, Edge)

**Test Coverage:**
- Modals: Dialog, ConfirmDialog, SettingsModal, etc.
- Popovers: LabelPopover, NoteActionsPopover, etc.
- Dropdowns: SortDropdown, FilterDropdown, etc.
- Workflows: Create Note, Edit Note, Delete Note, Search, Filter, etc.
- Accessibility: Keyboard navigation, screen reader, contrast ratios, touch targets
- Responsive: Mobile (320px-639px), Tablet (640px-1023px), Desktop (1024px+)
- Cross-browser: Chrome, Firefox, Safari, Edge

**Success Criteria:**
- ✅ All modals and popups tested
- ✅ All critical workflows tested
- ✅ Accessibility tests passing
- ✅ Responsive design tests passing
- ✅ Cross-browser tests passing
- ✅ Test coverage > 80%
- ✅ Tests run in < 5 minutes

**Dependencies:**
- None (tests can run in parallel with development)

---

### Story 16.1: Test Create Note Dialog

As a **quality assurance engineer**,
I want **a Playwright test for the Create Note dialog**,
So that **I can ensure the dialog works correctly**.

**Acceptance Criteria:**

**Given** I am on the notebook page
**When** I click the "Create Note" button
**Then** I should see the Create Note dialog open
**And** I should see input fields for title and content
**When** I fill in the title and content
**And** I click the "Save" button
**Then** the note should be created
**And** the dialog should close
**And** I should see the new note in the list

**Technical Notes:**
- Test opening the dialog
- Test filling in the form
- Test saving the note
- Test closing the dialog
- Test cancel button
- Test keyboard navigation (Tab, Enter, ESC)
- Test validation (empty fields)
- Test screen reader announcements

---

### Story 16.2: Test Edit Note Dialog

As a **quality assurance engineer**,
I want **a Playwright test for the Edit Note dialog**,
So that **I can ensure the dialog works correctly**.

**Acceptance Criteria:**

**Given** I am viewing a note
**When** I click the "Edit" button
**Then** I should see the Edit Note dialog open
**And** I should see the note's current title and content
**When** I modify the title and content
**And** I click the "Save" button
**Then** the note should be updated
**And** the dialog should close
**And** I should see the updated note content

**Technical Notes:**
- Test opening the dialog
- Test displaying current note data
- Test modifying the form
- Test saving the changes
- Test cancel button
- Test keyboard navigation
- Test validation

---

### Story 16.3: Test Delete Note Confirmation Dialog

As a **quality assurance engineer**,
I want **a Playwright test for the Delete Note confirmation dialog**,
So that **I can ensure the dialog works correctly**.

**Acceptance Criteria:**

**Given** I am viewing a note
**When** I click the "Delete" button
**Then** I should see the Delete Note confirmation dialog open
**And** I should see a confirmation message
**When** I click the "Confirm" button
**Then** the note should be deleted
**And** the dialog should close
**And** I should not see the note in the list
**When** I click the "Cancel" button
**Then** the dialog should close
**And** the note should not be deleted

**Technical Notes:**
- Test opening the dialog
- Test confirming deletion
- Test canceling deletion
- Test keyboard navigation (Enter to confirm, ESC to cancel)
- Test screen reader announcements

---

### Story 16.4: Test Settings Modal

As a **quality assurance engineer**,
I want **a Playwright test for the Settings modal**,
So that **I can ensure the modal works correctly**.

**Acceptance Criteria:**

**Given** I am on any page
**When** I click the "Settings" button in the navigation
**Then** I should see the Settings modal open
**And** I should see sections for: Personal Info, Account, Preferences, Notifications
**When** I modify a setting (e.g., change theme)
**And** I click the "Save" button
**Then** the setting should be saved
**And** the modal should close
**And** the change should be reflected in the UI
**When** I click the "Cancel" button
**Then** the modal should close
**And** the settings should not be saved

**Technical Notes:**
- Test opening the modal
- Test modifying settings
- Test saving changes
- Test canceling changes
- Test keyboard navigation
- Test tabbed sections
- Test screen reader announcements

---

### Story 16.5: Test AI Settings Modal

As a **quality assurance engineer**,
I want **a Playwright test for the AI Settings modal**,
So that **I can ensure the modal works correctly**.

**Acceptance Criteria:**

**Given** I am on any page
**When** I click the "AI Settings" button
**Then** I should see the AI Settings modal open
**And** I should see sections for: AI Provider, Feature Toggles, Advanced Options
**When** I select an AI provider
**And** I toggle a feature on/off
**And** I click the "Save" button
**Then** the settings should be saved
**And** the modal should close
**When** I click the "Cancel" button
**Then** the modal should close
**And** the settings should not be saved

**Technical Notes:**
- Test opening the modal
- Test selecting AI provider
- Test toggling features
- Test saving changes
- Test canceling changes
- Test keyboard navigation
- Test screen reader announcements

---

### Story 16.6: Test Label Popover

As a **quality assurance engineer**,
I want **a Playwright test for the Label popover**,
So that **I can ensure the popover works correctly**.

**Acceptance Criteria:**

**Given** I am viewing a note
**When** I click the "Labels" button
**Then** I should see the Label popover open
**And** I should see a list of existing labels
**And** I should see an input to create a new label
**When** I type a new label name and press Enter
**Then** the label should be created
**And** the label should be added to the note
**When** I click an existing label
**Then** the label should be toggled (added/removed)
**When** I click outside the popover
**Then** the popover should close

**Technical Notes:**
- Test opening the popover
- Test creating a new label
- Test toggling existing labels
- Test closing the popover
- Test keyboard navigation
- Test screen reader announcements

---

### Story 16.7: Test Note Actions Popover

As a **quality assurance engineer**,
I want **a Playwright test for the Note Actions popover**,
So that **I can ensure the popover works correctly**.

**Acceptance Criteria:**

**Given** I am viewing a note card
**When** I click the "Actions" button (three dots)
**Then** I should see the Note Actions popover open
**And** I should see options: Edit, Delete, Pin, Duplicate, etc.
**When** I click an action
**Then** the action should be executed
**And** the popover should close
**When** I click outside the popover
**Then** the popover should close

**Technical Notes:**
- Test opening the popover
- Test executing each action
- Test closing the popover
- Test keyboard navigation (arrow keys, Enter)
- Test screen reader announcements

---

### Story 16.8: Test Sort Dropdown

As a **quality assurance engineer**,
I want **a Playwright test for the Sort dropdown**,
So that **I can ensure the dropdown works correctly**.

**Acceptance Criteria:**

**Given** I am viewing a list of notes
**When** I click the "Sort" button
**Then** I should see the Sort dropdown open
**And** I should see options: Date, Title, A-Z, Z-A, etc.
**When** I click an option
**Then** the notes should be sorted by that option
**And** the dropdown should close
**When** I click outside the dropdown
**Then** the dropdown should close

**Technical Notes:**
- Test opening the dropdown
- Test selecting each sort option
- Test verifying the sort order
- Test closing the dropdown
- Test keyboard navigation (arrow keys, Enter, ESC)
- Test screen reader announcements

---

### Story 16.9: Test Filter Dropdown

As a **quality assurance engineer**,
I want **a Playwright test for the Filter dropdown**,
So that **I can ensure the dropdown works correctly**.

**Acceptance Criteria:**

**Given** I am viewing a list of notes
**When** I click the "Filter" button
**Then** I should see the Filter dropdown open
**And** I should see options: All Notes, Pinned, Favorites, Labels, etc.
**When** I select a filter
**Then** the notes should be filtered by that option
**And** the dropdown should close
**When** I click outside the dropdown
**Then** the dropdown should close

**Technical Notes:**
- Test opening the dropdown
- Test selecting each filter option
- Test verifying the filtered results
- Test closing the dropdown
- Test keyboard navigation
- Test screen reader announcements

---

### Story 16.10: Test Notebook Switcher Modal

As a **quality assurance engineer**,
I want **a Playwright test for the Notebook Switcher modal**,
So that **I can ensure the modal works correctly**.

**Acceptance Criteria:**

**Given** I am on any page
**When** I click the "Notebooks" button in the navigation
**Then** I should see the Notebook Switcher modal open
**And** I should see a list of all notebooks
**When** I click a notebook
**Then** I should navigate to that notebook
**And** the modal should close
**When** I click the "Create Notebook" button
**Then** I should see a form to create a new notebook
**When** I fill in the form and submit
**Then** the new notebook should be created
**And** I should navigate to the new notebook
**When** I click outside the modal
**Then** the modal should close

**Technical Notes:**
- Test opening the modal
- Test selecting a notebook
- Test creating a new notebook
- Test closing the modal
- Test keyboard navigation
- Test screen reader announcements

---

### Story 16.11: Test Keyboard Navigation

As a **quality assurance engineer**,
I want **Playwright tests for keyboard navigation across all pages**,
So that **I can ensure full keyboard accessibility**.

**Acceptance Criteria:**

**Given** I am using the app with a keyboard only
**When** I navigate with Tab
**Then** I should be able to focus all interactive elements
**When** I press Enter or Space
**Then** I should be able to activate buttons and links
**When** I press ESC
**Then** I should be able to close modals and popovers
**When** I use arrow keys
**Then** I should be able to navigate dropdowns and lists

**Technical Notes:**
- Test Tab navigation across all pages
- Test Enter/Space for activation
- Test ESC for closing modals
- Test arrow keys for dropdowns
- Test focus visible states
- Test logical tab order

---

### Story 16.12: Test Screen Reader Accessibility

As a **quality assurance engineer**,
I want **Playwright tests for screen reader accessibility**,
So that **I can ensure full screen reader support**.

**Acceptance Criteria:**

**Given** I am using the app with a screen reader
**When** I navigate through the interface
**Then** I should hear announcements for all interactive elements
**When** I open a modal
**Then** I should hear the modal title and content
**When** I close a modal
**Then** I should hear that the modal is closed
**When** I perform an action
**Then** I should hear a success or error message

**Technical Notes:**
- Test screen reader announcements for all elements
- Test ARIA labels and roles
- Test live regions for dynamic content
- Test focus management
- Test error and success announcements

---

### Story 16.13: Test Contrast Ratios

As a **quality assurance engineer**,
I want **Playwright tests for color contrast ratios**,
So that **I can ensure WCAG 2.1 AA compliance**.

**Acceptance Criteria:**

**Given** I am viewing the app in any theme
**When** I measure the contrast ratios
**Then** all text should have a contrast ratio of at least 4.5:1
**And** all UI elements should have a contrast ratio of at least 3:1
**And** the tests should pass for all themes (Light, Dark, Midnight, Sepia)

**Technical Notes:**
- Use Playwright to compute contrast ratios
- Test all text elements
- Test all UI elements
- Test all themes
- Ensure WCAG 2.1 AA compliance

---

### Story 16.14: Test Touch Targets

As a **quality assurance engineer**,
I want **Playwright tests for touch target sizes**,
So that **I can ensure WCAG 2.1 AA compliance**.

**Acceptance Criteria:**

**Given** I am viewing the app on mobile (< 768px)
**When** I measure the touch targets
**Then** all interactive elements should be at least 44x44px
**And** the tests should pass for all pages

**Technical Notes:**
- Use Playwright to measure element sizes
- Test all interactive elements on mobile
- Ensure minimum 44x44px touch targets
- Test on various mobile viewports

---

### Story 16.15: Test Responsive Design

As a **quality assurance engineer**,
I want **Playwright tests for responsive design**,
So that **I can ensure the app works on all screen sizes**.

**Acceptance Criteria:**

**Given** I am viewing the app on mobile (320px-639px)
**When** I interact with the interface
**Then** there should be no horizontal overflow
**And** the layout should be optimized for mobile
**When** I am viewing the app on tablet (640px-1023px)
**Then** the layout should adapt to tablet
**When** I am viewing the app on desktop (1024px+)
**Then** the layout should be optimized for desktop

**Technical Notes:**
- Test on mobile viewports (320px, 375px, 414px, 639px)
- Test on tablet viewports (640px, 768px, 1023px)
- Test on desktop viewports (1024px, 1440px, 1920px)
- Check for horizontal/vertical overflow
- Verify layout adaptation

---

### Story 16.16: Test Cross-Browser Compatibility

As a **quality assurance engineer**,
I want **Playwright tests for cross-browser compatibility**,
So that **I can ensure the app works on all browsers**.

**Acceptance Criteria:**

**Given** I am running tests on Chrome
**Then** all tests should pass
**Given** I am running tests on Firefox
**Then** all tests should pass
**Given** I am running tests on Safari
**Then** all tests should pass
**Given** I am running tests on Edge
**Then** all tests should pass

**Technical Notes:**
- Run tests on Chrome, Firefox, Safari, Edge
- Verify consistent behavior across browsers
- Handle browser-specific quirks
- Use Playwright's multi-browser support

---

### Story 16.17: Test Create Note Workflow

As a **quality assurance engineer**,
I want **a Playwright test for the Create Note workflow**,
So that **I can ensure the end-to-end workflow works correctly**.

**Acceptance Criteria:**

**Given** I am on the notebook page
**When** I click the "Create Note" button
**Then** I should see the Create Note dialog open
**When** I fill in the title and content
**And** I click the "Save" button
**Then** the note should be created
**And** I should see the note in the list
**When** I click the note
**Then** I should see the note details page

**Technical Notes:**
- Test the complete Create Note workflow
- Test all steps from click to view
- Test validation (empty fields)
- Test keyboard navigation
- Test screen reader announcements

---

### Story 16.18: Test Edit Note Workflow

As a **quality assurance engineer**,
I want **a Playwright test for the Edit Note workflow**,
So that **I can ensure the end-to-end workflow works correctly**.

**Acceptance Criteria:**

**Given** I am viewing a note
**When** I click the "Edit" button
**Then** I should see the Edit Note dialog open
**When** I modify the title and content
**And** I click the "Save" button
**Then** the note should be updated
**And** I should see the updated content

**Technical Notes:**
- Test the complete Edit Note workflow
- Test all steps from click to save
- Test keyboard navigation
- Test screen reader announcements

---

### Story 16.19: Test Delete Note Workflow

As a **quality assurance engineer**,
I want **a Playwright test for the Delete Note workflow**,
So that **I can ensure the end-to-end workflow works correctly**.

**Acceptance Criteria:**

**Given** I am viewing a note
**When** I click the "Delete" button
**Then** I should see the Delete Note confirmation dialog
**When** I click the "Confirm" button
**Then** the note should be deleted
**And** I should not see the note in the list
**When** I click the "Cancel" button
**Then** the dialog should close
**And** the note should not be deleted

**Technical Notes:**
- Test the complete Delete Note workflow
- Test confirmation and cancel
- Test keyboard navigation
- Test screen reader announcements

---

### Story 16.20: Test Search Workflow

As a **quality assurance engineer**,
I want **a Playwright test for the Search workflow**,
So that **I can ensure the end-to-end workflow works correctly**.

**Acceptance Criteria:**

**Given** I am on the notebook page
**When** I type in the search input
**Then** I should see search results update in real-time
**When** I click a filter
**Then** I should see filtered results
**When** I clear the search
**Then** I should see all notes

**Technical Notes:**
- Test the complete Search workflow
- Test real-time search
- Test filtering
- Test clearing search
- Test keyboard navigation
- Test screen reader announcements

---

## Epic 17: Innovation Features

Innovation features will be explored and implemented based on web research and industry trends. These features will differentiate Keep from competitors and provide unique value to users. This epic includes research, prototyping, and implementation of innovative ideas.

**Innovation Goals:**
- Differentiate Keep from competitors
- Provide unique value to users
- Leverage AI capabilities creatively
- Enhance productivity and user experience
- Explore emerging technologies

**Potential Features:**
- Voice-to-text notes
- AI-powered note summarization
- Smart templates
- Collaboration features (real-time, sharing)
- Integration with external services (calendar, email)
- Advanced search (natural language, fuzzy search)
- Note relationships and graph view
- Custom themes and branding
- Keyboard shortcuts and power user features
- Note export/import (Markdown, PDF, etc.)

**Success Criteria:**
- ✅ At least 5 innovative features implemented
- ✅ User testing shows positive feedback
- ✅ Differentiation from competitors achieved
- ✅ Performance impact minimal
- ✅ Accessibility maintained

**Dependencies:**
- None (can run in parallel with other epics)

---

### Story 17.1: Research Innovative Features

As a **product manager**,
I want **to research innovative features for note-taking apps**,
So that **I can propose features that differentiate Keep**.

**Acceptance Criteria:**

**When** I research note-taking apps
**Then** I should identify at least 10 innovative features
**And** I should categorize them by complexity and value
**And** I should prioritize them using MoSCoW method
**And** I should create a document with the research findings

**Technical Notes:**
- Research competitors (Notion, Evernote, Obsidian, etc.)
- Identify gaps in the market
- Propose unique features
- Prioritize features (Must Have, Should Have, Could Have, Won't Have)
- Document findings

---

### Story 17.2: Prototype Voice-to-Text Notes

As a **user**,
I want **to create notes using voice-to-text**,
So that **I can quickly capture ideas without typing**.

**Acceptance Criteria:**

**Given** I am on the create note page
**When** I click the "Record" button
**Then** I should see a recording indicator
**When** I speak
**Then** my speech should be transcribed to text in real-time
**When** I click the "Stop" button
**Then** the transcription should be complete
**And** I should be able to edit the text
**And** I should be able to save the note

**Technical Notes:**
- Use Web Speech API
- Real-time transcription
- Support multiple languages
- Error handling for microphone access
- Edit functionality
- Accessibility (keyboard navigation, screen reader)

---

### Story 17.3: Prototype AI-Powered Note Summarization

As a **user**,
I want **to generate AI-powered summaries of my notes**,
So that **I can quickly understand the main points**.

**Acceptance Criteria:**

**Given** I am viewing a long note
**When** I click the "Summarize" button
**Then** the note should be summarized by AI
**And** I should see a summary (bullet points or paragraph)
**And** I should be able to save the summary
**And** I should be able to regenerate the summary
**When** I view the summary
**Then** I should understand the main points of the note

**Technical Notes:**
- Use AI (Ollama or OpenAI) for summarization
- Summarization modes (bullet points, paragraph, etc.)
- Save summary as a separate note or append to original
- Regenerate functionality
- Error handling
- Accessibility (keyboard navigation, screen reader)

---

### Story 17.4: Prototype Smart Templates

As a **user**,
I want **to use smart templates for common note types**,
So that **I can quickly create structured notes**.

**Acceptance Criteria:**

**Given** I am creating a new note
**When** I select a template
**Then** the note should be populated with the template content
**And** I should see templates for: Meeting Notes, Daily Journal, Project Plan, etc.
**When** I customize the template
**Then** the changes should be saved
**When** I create a custom template
**Then** I should be able to save it for future use

**Technical Notes:**
- Template library (built-in and custom)
- Template variables (date, time, user, etc.)
- Custom template creation
- Template sharing (optional)
- Accessibility (keyboard navigation, screen reader)

---

### Story 17.5: Prototype Real-Time Collaboration

As a **user**,
I want **to collaborate on notes in real-time with others**,
So that **I can work together with my team**.

**Acceptance Criteria:**

**Given** I am viewing a note
**When** I share the note with another user
**Then** the other user should receive an invitation
**When** the other user accepts the invitation
**Then** they should be able to edit the note in real-time
**When** I edit the note
**Then** the other user should see my changes in real-time
**And** I should see their changes in real-time
**When** multiple users edit the same part
**Then** conflicts should be resolved

**Technical Notes:**
- Use WebSockets for real-time updates
- Operational Transformation (OT) or CRDT for conflict resolution
- Share functionality (email, link)
- Invitation system
- Presence indicators (who is viewing/editing)
- Accessibility (keyboard navigation, screen reader)

---

### Story 17.6: Prototype Note Relationships and Graph View

As a **user**,
I want **to visualize relationships between my notes**,
So that **I can discover connections and insights**.

**Acceptance Criteria:**

**Given** I have multiple notes with connections
**When** I view the graph view
**Then** I should see a visual graph of notes and connections
**And** I should be able to zoom and pan the graph
**And** I should be able to click a node to view the note
**When** I create a connection between notes
**Then** the connection should be shown in the graph
**When** I hover over a node
**Then** I should see a preview of the note

**Technical Notes:**
- Graph visualization library (D3.js, Cytoscape.js, etc.)
- Note connections (manual or AI-generated)
- Zoom and pan functionality
- Interactive nodes
- Accessibility (keyboard navigation, screen reader)

---

### Story 17.7: Prototype Advanced Natural Language Search

As a **user**,
I want **to search for notes using natural language queries**,
So that **I can find notes even if I don't remember exact keywords**.

**Acceptance Criteria:**

**Given** I am searching for notes
**When** I type a natural language query (e.g., "notes from last week about project X")
**Then** I should see relevant notes
**And** I should see how the notes match my query
**When** I refine my query
**Then** the results should update
**When** I click a result
**Then** I should see the note details

**Technical Notes:**
- Use AI for natural language understanding
- Query parsing and interpretation
- Relevance scoring
- Results ranking
- Accessibility (keyboard navigation, screen reader)

---

### Story 17.8: Prototype Keyboard Shortcuts

As a **power user**,
I want **to use keyboard shortcuts for common actions**,
So that **I can work more efficiently**.

**Acceptance Criteria:**

**Given** I am using the app
**When** I press Ctrl/Cmd + N
**Then** a new note should be created
**When** I press Ctrl/Cmd + F
**Then** the search input should be focused
**When** I press Ctrl/Cmd + /
**Then** I should see a list of keyboard shortcuts
**And** I should be able to customize keyboard shortcuts

**Technical Notes:**
- Keyboard shortcuts for common actions
- Shortcut help modal
- Customizable shortcuts
- Accessibility (screen reader announcements for shortcuts)
- Test on different platforms (Windows, Mac, Linux)

---

### Story 17.9: Prototype Note Export/Import

As a **user**,
I want **to export and import notes**,
So that **I can backup my data or move it to another app**.

**Acceptance Criteria:**

**Given** I am viewing notes
**When** I click "Export"
**Then** I should be able to select: Markdown, PDF, JSON, etc.
**When** I select a format
**Then** I should be able to download the exported file
**Given** I have an exported file
**When** I click "Import"
**Then** I should be able to upload the file
**And** the notes should be imported

**Technical Notes:**
- Export formats: Markdown, PDF, JSON, etc.
- Import formats: Markdown, JSON, etc.
- Batch export/import
- Error handling
- Accessibility (keyboard navigation, screen reader)

---

### Story 17.10: Prototype Custom Themes

As a **user**,
I want **to create custom themes**,
So that **I can personalize the app**.

**Acceptance Criteria:**

**Given** I am in settings
**When** I click "Customize Theme"
**Then** I should see a theme editor
**And** I should be able to customize: colors, fonts, spacing, etc.
**When** I save the theme
**Then** the theme should be applied
**And** I should be able to switch between themes
**When** I share the theme
**Then** others should be able to use it

**Technical Notes:**
- Theme editor (color picker, font selector, etc.)
- CSS variables for theming
- Theme presets
- Theme sharing (optional)
- Accessibility (contrast ratio checks)

---

## Epic Summary

### Total Epics: 17

### Epics 1-12 (CONSERVÉS - 78 User Stories existantes):
1. Epic 1: AI Title Suggestions
2. Epic 2: Hybrid Semantic Search
3. Epic 3: Memory Echo
4. Epic 4: Paragraph Reformulation
5. Epic 5: AI Settings & Privacy
6. Epic 6: Language Detection
7. Epic 7: Admin Dashboard & Analytics
8. Epic 8: Accessibility & Responsive
9. Epic 9: Simplify NoteCard
10. Epic 10: Design System
11. Epic 11: Settings Redesign
12. Epic 12: Mobile Experience

### Epics 13-17 (NOUVEAUX - 77 User Stories ajoutées):
13. Epic 13: Desktop Design Refactor (15 stories)
14. Epic 14: Admin & Profil Redesign (12 stories)
15. Epic 15: Mobile UX Overhaul (10 stories)
16. Epic 16: Playwright Test Suite (20 stories)
17. Epic 17: Innovation Features (20 stories)

### Total Stories: ~155 (78 conservés + 77 nouvelles)

---

**MISE À JOUR 2026-01-17**
**AUTEUR :** Assistant - Product Manager
**VALIDATION :** RAMEZ - Option 1 validée (conserver les 12 épics IA + ajouter les 5 nouveaux)
**RÉPONSES DE RAMEZ :** Q1=OUI (conserver), Q2=OUI (garder dans backlog), Q3=NON (pas de méta-données)
