Keep/_bmad-output/planning-artifacts/epics.md

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)