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

Epics & User Stories - Notebooks & Labels Contextuels

Project: Keep - Notebooks & Labels Contextuels Date: 2026-01-11 Status: READY FOR DEVELOPMENT Based on: PRD, Architecture (validated), Tech Specs (complete)

---

Table of Contents

1. Epic 1: Database Migration & Schema
2. Epic 2: State Management & Server Actions
3. Epic 3: Notebooks Sidebar UI
4. Epic 4: Advanced Drag & Drop
5. Epic 5: Contextual AI Features
6. Epic 6: Undo/Redo System

---

Epic 1: Database Migration & Schema

ID: EPIC-1 Priority: CRITICAL (Blocker) Phase: Foundation (Week 1) Story Points: 13 Dependencies: None

Description

Migrate the existing flat tags system to a contextual notebooks model without breaking changes. This epic creates the foundation for the entire feature.

User Stories

Story 1.1: Create Prisma Schema Migration

ID: US-1.1 Points: 3 Priority: Critical

As a Developer I want to extend the Prisma schema with Notebook and Label models So that the database supports the new notebooks feature

Acceptance Criteria:

• Notebook model created with fields: id, name, icon, color, order, userId
• Label model updated with required notebookId field
• Note model updated with optional notebookId field (null = Inbox)
• Many-to-many relation between Note and Label via junction table
• Cascade delete configured: Notebook → Labels (deleted), Notes (become general)
• Unique constraint on Label.notebookId + name
• Indexes created for performance: Note(userId, notebookId), Notebook(userId, order)
• Migration script runs successfully: npx prisma migrate dev
• Zero data loss (all existing notes preserved)

Technical Notes:

• See tech specs section 5.1 for complete schema
• Use onDelete: SetNull for Note.notebookId to preserve data
• Use onDelete: Cascade for Label.notebookId to clean up orphaned labels

Definition of Done:

• Migration tested locally
• Migration file committed to Git
• No breaking changes to existing queries

---

Story 1.2: Create Data Migration Script

ID: US-1.2 Points: 5 Priority: Critical

As a Developer I want to migrate existing labels to a default "Labels Migrés" notebook So that users don't lose any existing data

Acceptance Criteria:

• Migration script created: scripts/migrate-to-notebooks.ts
• Creates "Labels Migrés" notebook for each user
• Assigns all existing labels to this notebook
• Leaves all notes without notebook (they go to Inbox)
• Script logs progress and statistics
• Script can be run multiple times safely (idempotent)
• Rollback script created: scripts/rollback-notebooks.ts
• Tested with sample data (100+ notes, 20+ labels)
• Execution time < 5s for 1000 notes

Technical Notes:

• See tech specs section 5.2, 5.3
• Use transactions to prevent partial migration
• Add console.log for progress monitoring

Definition of Done:

• Migration runs successfully in development
• Rollback tested and working
• Documentation written for running migration

---

Story 1.3: Create Migration Tests

ID: US-1.3 Points: 2 Priority: High

As a Developer I want to test the migration script thoroughly So that I'm confident no data is lost in production

Acceptance Criteria:

• Test suite created: __tests__/migration.test.ts
• Test: Migration notebook created for each user
• Test: All labels migrated to migration notebook
• Test: No notes moved to notebooks (stay in Inbox)
• Test: Rollback restores original state
• Test: Migration is idempotent (can run twice)
• Test: Handles edge case (user with no labels)
• All tests passing

Definition of Done:

• Test coverage > 90% for migration code
• All tests passing consistently
• Tests run in CI/CD pipeline

---

Story 1.4: Document Migration Process

ID: US-1.4 Points: 1 Priority: Medium

As a Developer/Ops I want clear documentation for running the migration So that anyone can safely deploy the migration

Acceptance Criteria:

• Migration checklist created (pre-migration steps)
• Migration checklist created (post-migration verification)
• Rollback procedure documented
• Estimated downtime documented (should be < 1min)
• Backup requirements documented
• Troubleshooting guide for common issues

Definition of Done:

• Documentation reviewed by another developer
• Documentation tested in staging environment

---

Epic 1 Summary

Total Stories: 4 Total Points: 13 Estimated Time: 1-2 days

Risks:

• Data loss if migration fails (mitigated by rollback)
• Performance issues with large datasets (mitigated by batch processing)

Success Metrics:

• Zero data loss
• Migration time < 5s for 1000 notes
• All existing functionality still works

---

Epic 2: State Management & Server Actions

ID: EPIC-2 Priority: CRITICAL (Blocker) Phase: Foundation (Week 1-2) Story Points: 21 Dependencies: EPIC-1 (Database schema must exist)

Description

Implement the global state management layer using React Context and create all server actions for notebooks, labels, and note operations.

User Stories

Story 2.1: Create NotebooksContext

ID: US-2.1 Points: 5 Priority: Critical

As a Developer I want a global context for managing notebooks state So that all components can access and update notebooks data

Acceptance Criteria:

• NotebooksContext created with TypeScript interface
• NotebooksProvider wraps the application
• Context provides: notebooks, currentNotebook, currentLabels, error, isLoading
• Context provides actions: createNotebook, updateNotebook, deleteNotebook
• Context provides actions: setCurrentNotebook, updateNotebookOrder
• Uses useOptimistic for instant UI feedback on create/delete
• Loads initial notebooks data on mount
• Handles errors gracefully with error state
• Context TypeScript types exported for reuse

Technical Notes:

• See tech specs section 1.2 for complete implementation
• File location: app/context/notebooks-context.tsx
• Use useMemo and useCallback for performance

Definition of Done:

• TypeScript compilation with no errors
• Context works with test data
• Provider integrated in app/providers.tsx

---

Story 2.2: Create Notebook Server Actions

ID: US-2.2 Points: 5 Priority: Critical

As a Developer I want server actions for notebook CRUD operations So that the UI can create, update, delete notebooks

Acceptance Criteria:

• createNotebook(data) action created
  • Validates user is authenticated
  • Calculates next order value automatically
  • Returns created notebook
  • Calls revalidatePath('/')
• updateNotebook(id, data) action created
  • Validates ownership before updating
  • Updates name, icon, or color
  • Returns updated notebook
• deleteNotebook(id) action created
  • Validates ownership before deleting
  • Registers undo action before deleting
  • Deletes notebook (notes become general)
  • Calls revalidatePath('/')
• updateNotebookOrder(ids) action created
  • Updates order for all notebooks in transaction
  • Optimized for performance (bulk update)
• All actions have error handling with try/catch
• All actions validate input with Zod schemas

Technical Notes:

• See tech specs section 6.1
• File location: app/actions/notebooks.ts
• Use Prisma transactions for order update

Definition of Done:

• All actions tested manually with Postman/curl
• Error cases tested (unauthorized, not found)
• TypeScript types exported for client usage

---

Story 2.3: Create Label Server Actions

ID: US-2.3 Points: 3 Priority: High

As a Developer I want server actions for label CRUD operations So that the UI can manage labels within notebooks

Acceptance Criteria:

• createLabel(data) action created
  • Validates notebook ownership
  • Enforces unique constraint (name + notebookId)
  • Returns created label
• updateLabel(id, data) action created
  • Validates ownership via notebook
  • Returns updated label
• deleteLabel(id) action created
  • Validates ownership before deleting
  • Cascade delete removes label from all notes
  • Returns success
• All actions validate with Zod schemas
• All actions call revalidatePath('/')

Technical Notes:

• Labels belong to notebooks (contextual)
• Must verify notebook ownership before operations

Definition of Done:

• All actions tested
• Unique constraint enforced (duplicate names rejected)

---

Story 2.4: Create Note-Notebook Server Actions

ID: US-2.4 Points: 3 Priority: High

As a Developer I want server actions to move notes between notebooks So that users can organize their notes

Acceptance Criteria:

• moveNoteToNotebook(noteId, notebookId) action created
  • Validates note ownership
  • Accepts null for notebookId (move to Inbox)
  • Registers undo action before moving
  • Returns updated note
• attachLabel(noteId, labelId) action created
  • Validates note and label exist
  • Creates many-to-many relation
  • Prevents duplicate attachments
• detachLabel(noteId, labelId) action created
  • Validates relation exists
  • Removes relation
• All actions call revalidatePath('/')

Technical Notes:

• Use Prisma's connect/disconnect for many-to-many
• See tech specs section 6.1

Definition of Done:

• Tested moving notes between notebooks
• Tested attaching/detaching labels
• Undo/redo registered correctly

---

Story 2.5: Create AI Server Actions (Stub)

ID: US-2.5 Points: 2 Priority: Medium

As a Developer I want placeholder server actions for AI features So that the UI can integrate AI later (Epic 5)

Acceptance Criteria:

• suggestNotebook(noteContent) action created (returns null for now)
• suggestLabels(noteContent, notebookId) action created (returns [] for now)
• organizeInbox(noteIds) action created (returns empty map for now)
• Actions accept correct parameters
• Actions have correct return types
• Actions marked with TODO comments for Epic 5

Definition of Done:

• Actions callable from UI
• TypeScript types correct
• No runtime errors

---

Story 2.6: Write Tests for Context & Actions

ID: US-2.6 Points: 3 Priority: High

As a Developer I want tests for state management and server actions So that I'm confident the core logic works

Acceptance Criteria:

• Context tests created: __tests__/notebooks-context.test.tsx
  • Test: Loads notebooks on mount
  • Test: Creates notebook optimistically
  • Test: Updates current notebook
  • Test: Derives current labels correctly
• Action tests created: __tests__/notebooks-actions.test.ts
  • Test: Creates notebook successfully
  • Test: Rejects unauthorized access
  • Test: Validates input with Zod
  • Test: Handles errors gracefully
• Test coverage > 80%
• All tests passing

Definition of Done:

• Tests run in CI/CD
• Tests run locally with npm test
• No flaky tests

---

Epic 2 Summary

Total Stories: 6 Total Points: 21 Estimated Time: 2-3 days

Risks:

• Context performance issues with many notebooks (mitigated by useMemo)
• Server action rate limiting (not an issue for single-user)

Success Metrics:

• All CRUD operations working
• Optimistic UI feels instant
• No TypeScript errors

---

Epic 3: Notebooks Sidebar UI

ID: EPIC-3 Priority: HIGH Phase: Core UI (Week 2-3) Story Points: 21 Dependencies: EPIC-1, EPIC-2

Description

Create the sidebar UI for displaying and managing notebooks. This includes the notebook list, labels display, and basic navigation.

User Stories

Story 3.1: Create NotebooksSidebar Component

ID: US-3.1 Points: 5 Priority: High

As a User I want to see all my notebooks in a sidebar So that I can navigate between them

Acceptance Criteria:

• Sidebar component created: components/notebooks-sidebar.tsx
• Displays "Notes générales" (Inbox) at the top
• Displays all notebooks in list
• Shows notebook icon and name
• Shows note count for each notebook
• Highlights currently selected notebook
• Clicking notebook switches current notebook
• Loading state shown while fetching notebooks
• Error state shown if fetch fails
• Empty state shown if no notebooks exist
• Responsive sidebar width (desktop: 256px, mobile: collapsible)

Technical Notes:

• See tech specs section 2.2
• Uses useNotebooks() hook
• CSS modules for styling

Definition of Done:

• Sidebar displays correctly with test data
• Navigation works (clicking notebook updates grid)
• Styled to match existing Keep design

---

Story 3.2: Add Notebook Creation UI

ID: US-3.2 Points: 3 Priority: High

As a User I want to create new notebooks from the sidebar So that I can organize my notes

Acceptance Criteria:

• "+ New" button in sidebar header
• Clicking opens modal/dialog
• Modal contains: Name input, Icon picker, Color picker
• Icon picker shows common emojis (📚, 📝, 💼, 🏠, etc.)
• Color picker shows preset colors
• Name required, icon/color optional
• "Create" button creates notebook
• "Cancel" button closes modal
• Modal closes on successful creation
• New notebook appears in sidebar immediately (optimistic)
• Form validation (max 50 chars for name)

Technical Notes:

• Modal component: components/create-notebook-modal.tsx
• Uses createNotebookOptimistic action
• Zod validation on client and server

Definition of Done:

• Can create notebook
• Notebook appears instantly in sidebar
• Modal accessible (keyboard navigation)

---

Story 3.3: Add Notebook Management Actions

ID: US-3.3 Points: 3 Priority: Medium

As a User I want to edit and delete notebooks So that I can manage my organization

Acceptance Criteria:

• Hovering notebook shows "⋯" menu button
• Clicking menu shows: Edit, Delete options
• "Edit" opens modal with current values
• "Edit" modal allows changing name, icon, color
• "Delete" shows confirmation dialog
• Delete dialog explains: "Notes will become general"
• Confirming deletes notebook
• Notes from deleted notebook become general (Inbox)
• Can cancel both edit and delete operations

Technical Notes:

• Context menu or dropdown menu component
• Uses updateNotebook and deleteNotebook actions
• Undo toast appears after delete (Epic 6)

Definition of Done:

• Can rename notebook
• Can delete notebook (with confirmation)
• Notes preserved after deletion

---

Story 3.4: Display Labels in Sidebar

ID: US-3.4 Points: 3 Priority: Medium

As a User I want to see labels for the current notebook So that I know what labels are available

Acceptance Criteria:

• Labels shown under selected notebook in sidebar
• Labels appear when notebook is selected
• Labels appear when hovering notebook
• Each label shown as chip with name and color
• Label count shown (if > 0 notes have label)
• Labels hidden when switching to another notebook
• Animation when showing/hiding labels (slide down)
• Max 10 labels shown (scrollable if more)
• Empty state: "No labels yet" message

Technical Notes:

• Labels derived from currentLabels in context
• Sub-component: components/label-chip.tsx
• CSS animation for show/hide

Definition of Done:

• Labels display correctly
• Animation smooth
• Performance OK with 50+ labels

---

Story 3.5: Add Label Creation UI

ID: US-3.5 Points: 3 Priority: Medium

As a User I want to create labels for my notebook So that I can categorize notes within the notebook

Acceptance Criteria:

• "+ Label" button shown when notebook selected
• Clicking opens compact inline form or modal
• Form contains: Name input, Color picker
• Name required (max 30 chars)
• Color optional (random if not selected)
• "Create" button creates label
• New label appears immediately in sidebar
• Duplicate names rejected (within notebook)
• Form clears after creation

Technical Notes:

• Uses createLabel action
• Validation: unique constraint on notebookId + name

Definition of Done:

• Can create label
• Label appears instantly
• Duplicates prevented

---

Story 3.6: Add Label Management Actions

ID: US-3.6 Points: 2 Priority: Low

As a User I want to edit and delete labels So that I can fix mistakes or remove unused labels

Acceptance Criteria:

• Right-click label shows context menu
• Menu options: Edit name, Change color, Delete
• "Edit" opens inline edit or modal
• "Delete" shows confirmation (if label used on notes)
• Delete confirmation shows note count
• Confirming removes label from all notes
• Can cancel operations

Technical Notes:

• Context menu component
• Uses updateLabel and deleteLabel actions
• Cascade delete handled by Prisma

Definition of Done:

• Can rename label
• Can delete label (with confirmation)
• Notes no longer have deleted label

---

Story 3.7: Implement Note Filtering by Notebook

ID: US-3.7 Points: 5 Priority: Critical

As a User I want to see only notes from the selected notebook So that I can focus on one topic at a time

Acceptance Criteria:

• Selecting notebook filters notes in main grid
• Selecting "Notes générales" shows notes without notebook
• Note count updates correctly in sidebar
• Grid updates instantly when switching notebooks
• URL updates with notebook ID (optional, for sharing)
• Page title updates with notebook name
• Breadcrumb shows: Home > Notebook Name
• Can navigate back to "All notes" view
• Pagination works correctly (if implemented)
• Search works within filtered notes

Technical Notes:

• Modify app/page.tsx to filter notes by currentNotebook
• Pass notebookId to note query
• Update document title

Definition of Done:

• Switching notebooks works smoothly
• Note counts accurate
• Search respects notebook filter

---

Story 3.8: Style Sidebar to Match Keep Design

ID: US-3.8 Points: 2 Priority: Medium

As a User I want the sidebar to look consistent with Keep's design So that the UI feels polished

Acceptance Criteria:

• Sidebar uses Keep color scheme (grays, blues)
• Fonts match existing UI
• Spacing consistent (8px grid)
• Hover states smooth (150ms transition)
• Active state clearly visible
• Icons align correctly
• Scrollbar styled (custom webkit scrollbar)
• Dark mode supported (if Keep has dark mode)
• Mobile responsive (sidebar collapses)
• Accessibility: ARIA labels, keyboard nav

Definition of Done:

• Design approved by UX review
• Matches Keep design system
• Accessibility audit passed

---

Epic 3 Summary

Total Stories: 8 Total Points: 21 Estimated Time: 3-4 days

Risks:

• Sidebar performance with many notebooks (mitigated by virtual scrolling if needed)
• Mobile UX challenges (sidebar takes too much space)

Success Metrics:

• Sidebar navigation feels smooth
• Users can create and manage notebooks
• Design consistent with Keep

---

Epic 4: Advanced Drag & Drop

ID: EPIC-4 Priority: HIGH Phase: Drag & Drop (Week 3-4) Story Points: 13 Dependencies: EPIC-1, EPIC-2, EPIC-3

Description

Implement Muuri-based drag & drop for reordering notebooks and moving notes between notebooks. This provides the core interaction model for organizing content.

User Stories

Story 4.1: Implement Notebook Reordering

ID: US-4.1 Points: 5 Priority: High

As a User I want to drag notebooks to reorder them So that I can organize my sidebar the way I want

Acceptance Criteria:

• Notebooks can be dragged in sidebar
• Drag handle appears on hover (visual indicator)
• Other notebooks shift smoothly while dragging
• Placeholder shows where notebook will drop
• Drop updates order immediately (optimistic)
• Order saved to database via updateNotebookOrder
• Works on touch devices (mobile)
• Dragging disabled while "Notes générales" (always first)
• Drag feels smooth (60fps)
• Can't drag into invalid positions

Technical Notes:

• See tech specs section 2.2
• Uses Muuri library (same as masonry-grid)
• Configuration synced with masonry-grid for consistency
• Touch support via dragHandle option

Definition of Done:

• Can reorder notebooks smoothly
• Order persists after page refresh
• Works on mobile

---

Story 4.2: Add Visual Drag Feedback

ID: US-4.2 Points: 2 Priority: Medium

As a User I want visual feedback while dragging So that I know what's happening

Acceptance Criteria:

• Dragged item shows shadow
• Dragged item slightly transparent (0.5 opacity)
• Other items shift smoothly with animation
• Placeholder shows drop target clearly
• Cursor changes to "grabbing"
• Drop target highlighted on hover
• Animation duration: 150-200ms
• No jank or stuttering

Technical Notes:

• Muuri's dragPlaceholder config
• CSS transitions for smooth animations

Definition of Done:

• Drag feels polished
• Animations smooth at 60fps

---

Story 4.3: Implement Drag Notes to Sidebar

ID: US-4.3 Points: 5 Priority: High

As a User I want to drag notes from the grid to notebooks in sidebar So that I can quickly organize notes

Acceptance Criteria:

• Can drag note from masonry grid
• Can drop note onto notebook in sidebar
• Notebook highlights when note dragged over it
• "Notes générales" accepts dropped notes
• Drop moves note to target notebook
• Note disappears from current view (if filtered)
• Success animation/toast confirms move
• Works with multiple selected notes (if selection implemented)
• Drag cancelled if dropped outside valid target
• Undo button appears after move (Epic 6)

Technical Notes:

• Cross-container drag & drop
• Detect drop target via elementFromPoint
• Calls moveNoteToNotebook action
• See tech specs section 2.2

Definition of Done:

• Can drag notes to notebooks
• Notes move correctly
• Visual feedback clear

---

Story 4.4: Add Context Menu Move Alternative

ID: US-4.4 Points: 3 Priority: Medium

As a User I want to move notes via right-click menu So that I have an alternative to drag & drop

Acceptance Criteria:

• Right-clicking note shows context menu
• Menu has "Move to" submenu
• Submenu lists all notebooks
• Submenu has "Notes générales" option
• Clicking notebook moves note there
• Menu closes after selection
• Note disappears from current view
• Works with keyboard (accessibility)
• Menu positioned correctly (no overflow)

Technical Notes:

• Context menu component or native browser menu
• Fallback for users who can't use drag & drop

Definition of Done:

• Context menu works
• Keyboard accessible
• Alternative to drag & drop

---

Story 4.5: Add Drag Performance Optimizations

ID: US-4.5 Points: 2 Priority: Low

As a Developer I want drag & drop to perform well So that the UI feels smooth even with many items

Acceptance Criteria:

• Drag operations run at 60fps
• No layout thrashing during drag
• Uses requestAnimationFrame for updates
• Debounces rapid drag events
• Lazy loads heavy components during drag
• Profiled with 100+ notebooks/notes
• No memory leaks after drag operations

Technical Notes:

• Use React.memo for notebook items
• Avoid expensive computations during drag
• Clean up event listeners

Definition of Done:

• Performance test passed (100 items)
• No jank in profiler
• Memory stable after extended use

---

Epic 4 Summary

Total Stories: 5 Total Points: 13 Estimated Time: 2-3 days

Risks:

• Cross-container drag & drop complexity (mitigated by existing Muuri knowledge)
• Touch device support (mitigated by Muuri's built-in touch support)

Success Metrics:

• Drag & drop feels intuitive
• Users can organize notes easily
• Performance smooth (60fps)

---

Epic 5: Contextual AI Features

ID: EPIC-5 Priority: MEDIUM Phase: AI Integration (Week 4-5) Story Points: 21 Dependencies: EPIC-1, EPIC-2, EPIC-3

Description

Implement the 6 AI features that make notebooks intelligent. All AI features are contextual to the current notebook.

User Stories

Story 5.1: Implement Notebook Suggestion (IA1)

ID: US-5.1 Points: 3 Priority: High

As a User I want AI to suggest which notebook a note belongs to So that I can quickly file notes from my Inbox

Acceptance Criteria:

• When note created in Inbox, suggestion appears
• Suggestion shown as: "Move to [Notebook Name]?"
• Clicking suggestion moves note immediately
• Dismissing suggestion hides it
• Only suggests when confident (>70%)
• No suggestion if no good match
• Suggestion disappears after 30 seconds
• Works for notes with > 20 words of content
• Can manually trigger via button

Technical Notes:

• Implements NotebookSuggestionService (tech specs 4.1)
• Uses OpenAI API with optimized prompt
• Server action: suggestNotebookForNote
• Confidence threshold configurable

Definition of Done:

• Suggestions accurate (>70% user acceptance rate)
• Performance: < 2s for suggestion
• No annoying false positives

---

Story 5.2: Implement Label Suggestions (IA2)

ID: US-5.2 Points: 3 Priority: High

As a User I want AI to suggest labels from my current notebook So that I can quickly tag my notes

Acceptance Criteria:

• When editing note, label suggestions appear
• Suggestions filtered to current notebook's labels
• Shows top 3 suggested labels
• Clicking suggestion adds label to note
• Label appears in note's label list
• Can dismiss suggestions
• Only suggests if notebook has labels
• No suggestions if note too short (< 10 words)
• Suggestions update as note content changes

Technical Notes:

• Implements ContextualAutoTagService (tech specs 3.1)
• Uses existing auto-tagging infrastructure
• Filters suggestions by notebookId
• Server action: suggestContextualLabels

Definition of Done:

• Suggestions relevant (>60% user acceptance)
• Performance: < 1s for suggestions
• Doesn't annoy users

---

Story 5.3: Implement Batch Inbox Organization (IA3)

ID: US-5.3 Points: 5 Priority: Medium

As a User I want AI to organize multiple notes from my Inbox So that I can quickly clean up my Inbox

Acceptance Criteria:

• "Organize Inbox" button in Inbox view
• Button shows count of notes to organize
• Clicking opens confirmation dialog
• Dialog shows preview of planned organization
• Each note shows suggested notebook
• Can review/edit suggestions before confirming
• Confirming moves all notes in batch
• Progress bar shows organization progress
• Success message shows X notes moved
• Can undo batch operation (Epic 6)

Technical Notes:

• Server action: organizeInbox
• Batch AI calls (optimized)
• Updates all notes in transaction
• Uses NotebookSuggestionService

Definition of Done:

• Can organize 50 notes in < 30s
• Suggestions reasonable (>50% accuracy)
• Clear UI for review/edit

---

Story 5.4: Implement Auto Label Creation (IA4)

ID: US-5.4 Points: 3 Priority: Low

As a User I want AI to automatically create labels for recurring themes So that I don't have to manually create them

Acceptance Criteria:

• Background job detects recurring themes
• Creates label if theme appears in 3+ notes
• New label shown in sidebar
• Notification: "Created label: [Name]"
• Can delete auto-created labels
• Only runs if notebook has < 50 labels
• Runs once per day (not real-time)
• Respects unique constraint
• Uses random color for new label

Technical Notes:

• Implements createLabelIfRecurring (tech specs 3.1)
• Could be cron job or triggered action
• Threshold configurable (default: 3 occurrences)

Definition of Done:

• Creates useful labels (>50% kept by users)
• Doesn't create spam
• Performance: < 10s for 100 notes

---

Story 5.5: Implement Contextual Semantic Search (IA5)

ID: US-5.5 Points: 5 Priority: High

As a User I want semantic search limited to my current notebook So that I find relevant notes without noise

Acceptance Criteria:

• Search box shows notebook context
• Placeholder: "Search in [Notebook Name]"
• Search only returns notes from current notebook
• Search in "Notes générales" searches only Inbox
• Results ranked by semantic similarity
• Shows top 20 results
• Results highlight matching terms
• Search < 300ms for 1000 notes
• Can opt-out to "Search All Notebooks"
• Search respects label filters (if implemented)

Technical Notes:

• Server action: contextualSemanticSearch
• Filters Prisma query by notebookId
• Uses existing embedding search
• Tech specs section 7 (architecture decision 7)

Definition of Done:

• Search results relevant
• Performance acceptable
• Context clear in UI

---

Story 5.6: Implement Notebook Summary (IA6)

ID: US-5.6 Points: 4 Priority: Low

As a User I want an AI summary of my notebook So that I can quickly understand what's in it

Acceptance Criteria:

• "Summarize" button in notebook menu
• Clicking generates summary of all notes
• Summary shows key themes (5-10 bullets)
• Summary lists top labels by usage
• Summary shows note count
• Summary generation takes < 5s
• Can copy summary to clipboard
• Summary cached for 1 hour
• Shows loading state while generating
• Error message if generation fails

Technical Notes:

• New service: NotebookSummaryService
• Aggregates all note content
• Uses OpenAI summarization
• Could use map-reduce for large notebooks

Definition of Done:

• Summaries useful (>70% satisfaction)
• Performance acceptable
• Works with notebooks up to 500 notes

---

Story 5.7: Add AI Settings and Controls

ID: US-5.7 Points: 2 Priority: Medium

As a User I want to control AI features So that they don't annoy me

Acceptance Criteria:

• Settings page for AI features
• Toggle for each IA feature (IA1-IA6)
• Toggle for all AI features
• Sensitivity slider (how aggressive suggestions are)
• "Never suggest for this notebook" option
• Clear explanation of each feature
• Privacy note: "AI runs on your content"

Definition of Done:

• Users can disable annoying features
• Settings easy to understand
• Privacy addressed

---

Story 5.8: Add AI Performance Monitoring

ID: US-5.8 Points: 2 Priority: Low

As a Developer I want to monitor AI feature performance So that I can improve them

Acceptance Criteria:

• Track suggestion acceptance rate
• Track suggestion rejection rate
• Track AI API costs
• Track average response time
• Dashboard shows metrics
• Alerts for unusual patterns
• Export logs for analysis

Definition of Done:

• Metrics collected
• Dashboard usable
• Costs tracked

---

Epic 5 Summary

Total Stories: 8 Total Points: 21 Estimated Time: 3-4 days

Risks:

• OpenAI API costs (mitigated by caching, limits)
• Poor suggestions annoy users (mitigated by confidence thresholds)
• Performance issues with large notebooks (mitigated by batching)

Success Metrics:

• 60% user acceptance of suggestions

• < 2s average response time
• AI features helpful, not annoying

---

Epic 6: Undo/Redo System

ID: EPIC-6 Priority: MEDIUM Phase: Polish (Week 5) Story Points: 8 Dependencies: EPIC-2, EPIC-3, EPIC-4

Description

Implement an undo/redo system for destructive actions so users can explore without fear.

User Stories

Story 6.1: Implement Undo History

ID: US-6.1 Points: 3 Priority: High

As a Developer I want an undo history system So that users can undo their actions

Acceptance Criteria:

• UndoHistory class created (tech specs 8.1)
• Stores last 20 actions
• Actions: MOVE_NOTE, DELETE_NOTEBOOK, DELETE_LABEL, REORDER
• Each action has: type, timestamp, undo function, description
• add(action) adds to history
• undo() executes last action's undo function
• getLastAction() returns most recent action
• History persists in memory (session only)
• History cleared on page refresh

Technical Notes:

• Tech specs section 8 (architecture decision 8)
• File: lib/undo-history.ts
• In-memory storage (not persistent)

Definition of Done:

• History class working
• Unit tests passing
• Integrated with server actions

---

Story 6.2: Register Undo Actions

ID: US-6.2 Points: 2 Priority: High

As a Developer I want destructive actions to register undo So that users can undo them

Acceptance Criteria:

• moveNoteToNotebook registers undo
• deleteNotebook registers undo
• deleteLabel registers undo
• updateNotebookOrder registers undo
• Undo function restores previous state
• Undo function calls revalidatePath('/')
• Error handling if undo fails
• Only one undo level deep (no redo for MVP)

Technical Notes:

• Modify actions from Epic 2
• Add undoHistory.add() calls
• Store previous state for rollback

Definition of Done:

• All destructive actions register undo
• Undo works correctly
• Tested manually

---

Story 6.3: Create Undo Toast UI

ID: US-6.3 Points: 2 Priority: Medium

As a User I want to see an undo notification after actions So that I can undo if I made a mistake

Acceptance Criteria:

• Toast appears after destructive action
• Toast shows action description
• Toast has "Undo" button
• Clicking "Undo" reverts action
• Toast auto-dismisses after 10 seconds
• Hovering toast keeps it visible
• Can manually dismiss toast (× button)
• Toast positioned bottom-right
• Animation smooth (slide in/fade out)
• Only one toast at a time

Technical Notes:

• Component: components/undo-toast.tsx
• Tech specs section 8.1
• Uses getLastAction() from history

Definition of Done:

• Toast appears after actions
• Undo button works
• UX polished

---

Story 6.4: Add Undo Keyboard Shortcut

ID: US-6.4 Points: 1 Priority: Low

As a User I want to undo with keyboard shortcut So that I can quickly fix mistakes

Acceptance Criteria:

• Ctrl+Z (or Cmd+Z on Mac) triggers undo
• Works globally (not just when toast visible)
• Shows feedback: "Undo: [action description]"
• Does nothing if no history
• Does not interfere with browser undo
• Documented in help

Definition of Done:

• Keyboard shortcut works
• Doesn't conflict with browser
• Feedback clear

---

Epic 6 Summary

Total Stories: 4 Total Points: 8 Estimated Time: 1-2 days

Risks:

• Undo state management complexity (mitigated by simple in-memory history)
• Undo conflicts with concurrent updates (rare in single-user)

Success Metrics:

• Users can undo actions
• Undo works correctly
• UX feels safe

---

Overall Summary

All Epics

Epic	Points	Phase	Dependencies
EPIC-1: Database Migration	13	Week 1	None
EPIC-2: State Management	21	Week 1-2	EPIC-1
EPIC-3: Sidebar UI	21	Week 2-3	EPIC-1, EPIC-2
EPIC-4: Drag & Drop	13	Week 3-4	EPIC-1, EPIC-2, EPIC-3
EPIC-5: AI Features	21	Week 4-5	EPIC-1, EPIC-2, EPIC-3
EPIC-6: Undo/Redo	8	Week 5	EPIC-2, EPIC-3, EPIC-4

Total Story Points: 97 Estimated Time: 5-6 weeks Total Stories: 34

Implementation Priority

Must Have (MVP):

• EPIC-1: Database Migration
• EPIC-2: State Management & Actions
• EPIC-3: Sidebar UI (stories 3.1, 3.2, 3.7)
• EPIC-4: Drag & Drop (stories 4.1, 4.3)

Should Have:

• EPIC-3: Remaining stories
• EPIC-4: Remaining stories
• EPIC-5: AI features (stories 5.1, 5.2, 5.5)
• EPIC-6: Undo/Redo (stories 6.1, 6.2, 6.3)

Could Have:

• EPIC-5: Advanced AI (stories 5.3, 5.4, 5.6)
• EPIC-6: Keyboard undo

Won't Have (Future):

• Multi-notebook search
• Notebook sharing
• Note templates

Risk Register

Risk	Impact	Probability	Mitigation
Data loss during migration	CRITICAL	LOW	Backup, rollback, testing
Poor AI suggestions	MEDIUM	MEDIUM	Confidence thresholds, user feedback
Performance with 1000+ notes	HIGH	MEDIUM	Indexes, pagination, profiling
Drag & drop bugs	MEDIUM	LOW	Extensive testing, fallback menus
OpenAI API costs	MEDIUM	LOW	Caching, rate limits

Success Criteria

Technical:

• All 34 stories completed
• Zero data loss
• < 2s AI response time
• < 300ms search time
• 60fps drag & drop
• 80%+ test coverage

User:

• Users can create notebooks
• Users can organize notes
• AI suggestions helpful (>60% acceptance)
• Undo works reliably
• Performance acceptable

Business:

• Migration successful
• No breaking changes
• User adoption > 70%
• Support tickets decreased

---

Document Status: ✅ COMPLETE Ready for Sprint Planning: YES Total Epics: 6 Total Stories: 34 Total Story Points: 97

---

This Epic & User Story document was created based on validated Architecture and complete Tech Specs. Date: 2026-01-11 Author: Winston (Architect AI Agent)