Version: 1.0
Last Updated: January 8, 2026
Project: Open Notes - User-Owned, AI-Assisted Note System
This document captures functional requirements for Open Notes using structured EARS (Easy Approach to Requirements Syntax) notation. Requirements are organized by feature domain with associated user stories and acceptance criteria.
- Note Management
- Content Editing
- Category System
- Tagging System
- Search and Navigation
- AI Enrichment
- Settings and Configuration
- Persistence and Storage
- User Interface
- Data Export
As a user
I want to create new notes
So that I can capture my thoughts and information
REQ-NOTE-001: The system shall create a new note when the user invokes the create note command.
REQ-NOTE-002: When a new note is created, the system shall assign a unique identifier with format [prefix]-[timestamp]-[random].
REQ-NOTE-003: When a new note is created, the system shall initialize the note with:
- An "Untitled Note" default title
- Empty content blocks array
- Current timestamp as createdAt and updatedAt
- Empty enrichment blocks array
- Empty user and system tags
REQ-NOTE-004: If manual categories exist, then the system shall present a category selection modal when creating a note.
REQ-NOTE-005: If only one manual category exists and no AI categories exist, then the system shall automatically assign that category to the new note.
REQ-NOTE-006: If no manual categories exist, then the system shall create the note with undefined category for AI classification.
As a user
I want to edit and update my notes
So that I can refine and expand my content
REQ-NOTE-007: When a user modifies note content or title, the system shall update the note's updatedAt timestamp.
REQ-NOTE-008: The system shall persist note changes to storage within the configured auto-save interval.
REQ-NOTE-009: While auto-save is in progress, the system shall display a saving indicator to the user.
REQ-NOTE-010: When note save completes successfully, the system shall display a saved confirmation indicator.
REQ-NOTE-011: The system shall implement debounced saving to prevent excessive write operations during active editing.
As a user
I want to delete notes I no longer need
So that I can maintain a clean workspace
REQ-NOTE-012: When a user initiates note deletion, the system shall display a confirmation dialog.
REQ-NOTE-013: If the user confirms deletion, then the system shall remove the note from storage.
REQ-NOTE-014: If the user confirms deletion, then the system shall remove the note from all local state stores.
REQ-NOTE-015: When a note is deleted, the system shall automatically select another note if available.
As a user
I want to see when notes were created and last modified
So that I can track the history of my content
REQ-NOTE-016: The system shall display the note's last modified time in relative format (e.g., "2 hours ago").
REQ-NOTE-017: The system shall display the note's creation timestamp.
REQ-NOTE-018: The system shall update displayed relative times automatically to maintain accuracy.
As a user
I want to format my note content with rich text features
So that I can create well-structured, readable notes
REQ-EDIT-001: The system shall provide a rich text editor with block-based content structure.
REQ-EDIT-002: The system shall support the following block types:
- Paragraphs
- Headings (multiple levels)
- Lists (ordered and unordered)
- Code blocks
- Tables
- Images
- Links
REQ-EDIT-003: The system shall support the following inline text formatting:
- Bold
- Italic
- Underline
- Strikethrough
- Code (inline)
- Hyperlinks
REQ-EDIT-004: The system shall serialize content as structured JSON blocks.
REQ-EDIT-005: When content is modified, the system shall preserve the block structure and formatting.
As a user
I want my changes automatically saved
So that I don't lose work due to forgotten manual saves
REQ-EDIT-006: Where auto-save is enabled in settings, the system shall automatically save note changes.
REQ-EDIT-007: The system shall use the configured auto-save interval from settings (default: 10 seconds).
REQ-EDIT-008: While the user is actively typing, the system shall debounce save operations to prevent performance issues.
REQ-EDIT-009: When switching between notes, the system shall immediately save any pending changes.
As a user
I want to edit note titles separately from content
So that I can quickly identify and organize my notes
REQ-EDIT-010: The system shall provide a dedicated title input field separate from the content editor.
REQ-EDIT-011: When a new note is created, the system shall automatically focus the title input field.
REQ-EDIT-012: When the title is modified, the system shall update the note title in the navigation tree immediately.
As a user
I want to create custom categories
So that I can organize my notes by topic or purpose
REQ-CAT-001: The system shall allow users to create new categories with a unique name.
REQ-CAT-002: When a category is created, the system shall assign it a unique identifier with format cat-[timestamp]-[random].
REQ-CAT-003: When a category is created, the system shall assign it a random color from the predefined palette.
REQ-CAT-004: The system shall support the following category properties:
- Name (required)
- Color (required)
- Enrichment prompt (optional)
- No enrichment flag (boolean)
REQ-CAT-005: The system shall provide a color palette with 20 predefined colors for category assignment.
As a user
I want to categorize my notes
So that I can group related content together
REQ-CAT-006: The system shall allow assignment of zero or one category per note.
REQ-CAT-007: When a category is assigned to a note, the system shall persist the assignment to storage.
REQ-CAT-008: When a category is assigned, the system shall display the category indicator in the note editor.
REQ-CAT-009: The system shall allow users to change a note's category at any time.
REQ-CAT-010: The system shall allow users to remove a category from a note.
As a user
I want to edit and delete categories
So that I can maintain a relevant categorization system
REQ-CAT-011: The system shall allow users to modify category properties after creation.
REQ-CAT-012: The system shall allow users to delete categories.
REQ-CAT-013: When a category is deleted, the system shall remove the category reference from all notes using it.
REQ-CAT-014: The system shall persist category changes to storage immediately.
As a user
I want to specify whether categories should use AI enrichment
So that I can control AI involvement per category
REQ-CAT-015: The system shall support manual categories (noEnrichment = true) that disable AI enrichment.
REQ-CAT-016: The system shall support AI-assisted categories (noEnrichment = false) with custom enrichment prompts.
REQ-CAT-017: Where a category has noEnrichment flag set to false, the system shall use the category's enrichment prompt for AI operations.
REQ-CAT-018: Where a category has an enrichment prompt defined, the system shall display and allow editing of the prompt.
As a user
I want to view notes filtered by category
So that I can focus on specific topics
REQ-CAT-019: The system shall display notes grouped by category in the navigation tree.
REQ-CAT-020: The system shall display the count of notes per category.
REQ-CAT-021: The system shall allow users to expand/collapse category groups.
REQ-CAT-022: When a category group is collapsed, the system shall hide the notes within that category.
REQ-CAT-023: The system shall provide an "Uncategorized" group for notes without assigned categories.
As a user
I want to tag my notes with keywords
So that I can create cross-cutting classifications
REQ-TAG-001: The system shall allow users to add multiple tags to any note.
REQ-TAG-002: When a tag is added, the system shall normalize the tag name (lowercase, trimmed).
REQ-TAG-003: When a tag is added to a note, the system shall add it to the user tags array.
REQ-TAG-004: The system shall assign each tag a color from the predefined palette based on hash of tag name.
REQ-TAG-005: The system shall add new tags to the global tags collection when first used.
As a user
I want to remove tags from notes
So that I can correct mis-tagging or clean up obsolete tags
REQ-TAG-006: The system shall allow users to remove tags from individual notes.
REQ-TAG-007: When a tag is removed from a note, the system shall remove it from the note's user tags array.
REQ-TAG-008: The system shall allow users to delete tags globally.
REQ-TAG-009: When a tag is deleted globally, the system shall remove it from all notes that reference it.
As a user
I want to distinguish between my manual tags and AI-generated tags
So that I maintain control over manual classifications
REQ-TAG-010: The system shall maintain separate arrays for user tags and system tags.
REQ-TAG-011: The system shall store user-created tags in the note's tags.user array.
REQ-TAG-012: The system shall store AI-generated tags in the note's tags.system array.
REQ-TAG-013: The system shall display user tags and system tags with visual differentiation.
As a user
I want to filter notes by tags
So that I can find related content across categories
REQ-TAG-014: The system shall provide a function to retrieve all notes with a specific tag.
REQ-TAG-015: When a tag is clicked in the UI, the system shall filter the notes list to show only notes with that tag.
REQ-TAG-016: The system shall display the tag name and count in filter results.
As a user
I want to search across my notes
So that I can quickly find specific content
REQ-SEARCH-001: The system shall provide a search input accessible via command palette.
REQ-SEARCH-002: When a search query is entered, the system shall filter notes by title matching the query.
REQ-SEARCH-003: The system shall perform case-insensitive search matching.
REQ-SEARCH-004: When search is active, the system shall display search results in a dedicated view.
REQ-SEARCH-005: When search is cleared, the system shall return to the previous view mode.
As a user
I want to access commands via keyboard shortcuts
So that I can work efficiently without mouse
REQ-SEARCH-006: The system shall provide a command palette accessible via Ctrl+K (Windows) or Cmd+K (macOS).
REQ-SEARCH-007: The command palette shall allow quick note selection by title search.
REQ-SEARCH-008: The command palette shall display keyboard shortcuts for common actions.
REQ-SEARCH-009: When a note is selected from the command palette, the system shall navigate to that note.
As a user
I want to view my notes organized by different criteria
So that I can navigate based on my current needs
REQ-NAV-001: The system shall support the following view modes:
- Category view (grouped by category)
- Time view (grouped by time period)
- Flat view (all notes in list)
- Search view (filtered results)
REQ-NAV-002: In time view, the system shall group notes into:
- Today
- This Week
- Earlier
REQ-NAV-003: The system shall sort notes by updatedAt timestamp in descending order (most recent first).
REQ-NAV-004: When switching view modes, the system shall maintain the selected note if visible in new view.
As a user
I want to quickly access recently modified notes
So that I can continue working on current tasks
REQ-NAV-005: The system shall provide a function to retrieve recently updated notes.
REQ-NAV-006: The system shall support limiting the number of recent notes returned (default: no limit).
REQ-NAV-007: The system shall sort recent notes by updatedAt in descending order.
As a user
I want AI insights added separately from my content
So that my original notes remain intact
REQ-AI-001: The system shall store user content in contentBlocks array.
REQ-AI-002: The system shall store AI-generated content in enrichmentBlocks array.
REQ-AI-003: The system shall never modify contentBlocks through AI operations.
REQ-AI-004: When AI enrichment is generated, the system shall replace the entire enrichmentBlocks array.
REQ-AI-005: The system shall allow users to clear enrichment blocks without affecting content blocks.
As a user
I want different AI prompts for different categories
So that enrichment is relevant to the note type
REQ-AI-006: Where a note has an assigned category, the system shall use that category's enrichment prompt.
REQ-AI-007: Where a note's category has noEnrichment set to true, the system shall skip AI enrichment.
REQ-AI-008: Where a note has no category, the system shall use the generic enrichment prompt from settings.
REQ-AI-009: The system shall support custom enrichment prompts per category.
As a user
I want to show or hide AI enrichment
So that I can focus on original content when needed
REQ-AI-010: The system shall provide a toggle to show/hide enrichment content.
REQ-AI-011: When enrichment view is disabled, the system shall display only contentBlocks.
REQ-AI-012: When enrichment view is enabled, the system shall display both contentBlocks and enrichmentBlocks.
As a user
I want to configure which AI models to use
So that I can control cost, privacy, and capabilities
REQ-AI-013: The system shall support configuration of separate language and embedding models.
REQ-AI-014: For each model, the system shall store:
- Provider name
- Model name
- Optional base URL
- Optional API key
REQ-AI-015: The system shall support local, self-hosted, and cloud AI providers.
REQ-AI-016: Where no AI models are configured, the system shall operate without AI features.
As a user
I want to customize the application appearance
So that I can work comfortably in different environments
REQ-SET-001: The system shall support the following theme options:
- Light
- Dark
- System (follow OS preference)
REQ-SET-002: The system shall support the following font size options:
- Small
- Medium (default)
- Large
REQ-SET-003: When theme is changed, the system shall apply the new theme immediately.
REQ-SET-004: When font size is changed, the system shall update all text rendering immediately.
As a user
I want to configure editor behavior
So that the system works according to my preferences
REQ-SET-005: The system shall provide a setting to enable/disable auto-save.
REQ-SET-006: The system shall provide a setting to configure auto-save interval (in seconds).
REQ-SET-007: When auto-save is disabled, the system shall require manual save actions.
REQ-SET-008: The system shall persist editor settings changes immediately.
As a user
I want to manage categories from settings
So that I can configure my organization system centrally
REQ-SET-009: The system shall provide a settings panel for category management.
REQ-SET-010: The settings panel shall allow creating new categories.
REQ-SET-011: The settings panel shall allow editing existing categories.
REQ-SET-012: The settings panel shall allow deleting categories.
REQ-SET-013: The settings panel shall display all configured categories.
As a user
I want to customize AI prompts
So that enrichment matches my needs
REQ-SET-014: The system shall provide editable generic enrichment prompt.
REQ-SET-015: The system shall provide editable category recognition prompt.
REQ-SET-016: The system shall support template variables in prompts (e.g., {% for category in categories %}).
REQ-SET-017: When prompts are modified, the system shall persist changes immediately.
As a user
I want my data stored reliably
So that I don't lose my notes
REQ-STORE-001: The system shall use adapter pattern for all persistence operations.
REQ-STORE-002: The system shall provide separate adapters for:
- Notes persistence
- Categories persistence
- Tags persistence
- Settings persistence
REQ-STORE-003: The default implementation shall use localStorage for persistence.
REQ-STORE-004: The system shall support alternative storage adapters (e.g., file system, database).
As a user
I want my data loaded when the application starts
So that I can immediately access my notes
REQ-STORE-005: When the application starts, the system shall hydrate all stores from persistence.
REQ-STORE-006: The system shall hydrate stores in the following order:
- Settings
- Categories
- Tags
- Notes
REQ-STORE-007: If hydration fails, the system shall display an error message.
REQ-STORE-008: After successful hydration, the system shall select the first available note if any exist.
As a user
I want immediate UI response to my actions
So that the application feels fast and responsive
REQ-STORE-009: When a note is created, the system shall update local state immediately with a temporary ID.
REQ-STORE-010: When the persistence operation completes, the system shall replace the temporary ID with the actual ID.
REQ-STORE-011: If a persistence operation fails, the system shall revert the optimistic update.
REQ-STORE-012: If a persistence operation fails, the system shall display an error message to the user.
As a user
I want multiple related changes persisted efficiently
So that the application maintains performance
REQ-STORE-013: The system shall support batch update operations for notes.
REQ-STORE-014: When performing batch updates, the system shall update all local state first.
REQ-STORE-015: When performing batch updates, the system shall persist all changes in a single operation.
As a user
I want the interface to work on different screen sizes
So that I can use the application on various devices
REQ-UI-001: The system shall provide a responsive layout that adapts to screen width.
REQ-UI-002: On mobile devices, the system shall show a simplified navigation interface.
REQ-UI-003: On desktop, the system shall display a collapsible sidebar navigation.
REQ-UI-004: The system shall persist sidebar collapsed/expanded state across sessions.
As a user
I want keyboard shortcuts for common actions
So that I can work efficiently
REQ-UI-005: The system shall support Ctrl+K (Cmd+K on macOS) to open command palette.
REQ-UI-006: The system shall support Ctrl+N (Cmd+N on macOS) to create new note.
REQ-UI-007: The system shall display keyboard shortcuts in tooltips and UI elements.
REQ-UI-008: On macOS, the system shall use Command key instead of Control for shortcuts.
As a user
I want clear feedback on system actions
So that I understand what's happening
REQ-UI-009: When a save operation is in progress, the system shall display a saving indicator.
REQ-UI-010: When a save operation completes, the system shall display a saved confirmation.
REQ-UI-011: When an error occurs, the system shall display an error message.
REQ-UI-012: When a long-running operation is in progress, the system shall display a loading indicator.
As a user
I want to collapse the sidebar
So that I can maximize editor space when needed
REQ-UI-013: The system shall provide a toggle button to collapse/expand the sidebar.
REQ-UI-014: When collapsed, the system shall hide the sidebar navigation.
REQ-UI-015: When collapsed, the system shall expand the editor area to use available space.
REQ-UI-016: The system shall display appropriate icon for current collapsed state.
As a user
I want to quickly switch between light and dark themes
So that I can adapt to lighting conditions
REQ-UI-017: The system shall provide a theme toggle button in the interface.
REQ-UI-018: When theme toggle is clicked, the system shall cycle through theme options.
REQ-UI-019: When system theme is selected, the system shall follow OS dark mode preference.
As a user
I want to export notes to Markdown format
So that I can use my content in other applications
REQ-EXPORT-001: The system shall provide an export function to convert notes to Markdown.
REQ-EXPORT-002: When exporting to Markdown, the system shall convert structured blocks to Markdown syntax.
REQ-EXPORT-003: The system shall support export of individual notes.
REQ-EXPORT-004: The exported Markdown shall preserve:
- Headings
- Lists
- Text formatting (bold, italic)
- Links
- Code blocks
As a user
I want to download my note content
So that I can back up or share my work
REQ-EXPORT-005: The system shall provide a download function accessible from the note editor.
REQ-EXPORT-006: When downloading a note, the system shall generate a file with the note title as filename.
REQ-EXPORT-007: The system shall sanitize filenames to remove invalid characters.
This document uses the following EARS patterns:
- Ubiquitous: "The system shall [requirement]"
- Event-driven: "When [trigger], the system shall [requirement]"
- Unwanted behavior: "If [condition], then the system shall [requirement]"
- State-driven: "While [state], the system shall [requirement]"
- Optional: "Where [feature is included], the system shall [requirement]"
| Feature Domain | Requirement IDs | Related Components |
|---|---|---|
| Note Management | REQ-NOTE-001 to REQ-NOTE-018 | notes.store.ts, notes-workspace.tsx |
| Content Editing | REQ-EDIT-001 to REQ-EDIT-012 | note-editor.tsx, plate-editor.tsx |
| Category System | REQ-CAT-001 to REQ-CAT-023 | categories.store.ts, category-modal.tsx |
| Tagging System | REQ-TAG-001 to REQ-TAG-016 | tags.store.ts, tag-utils.ts |
| Search/Navigation | REQ-SEARCH-001 to REQ-NAV-007 | command-palette.tsx, notes-tree.tsx |
| AI Enrichment | REQ-AI-001 to REQ-AI-016 | notes.store.ts, settings.store.ts |
| Settings | REQ-SET-001 to REQ-SET-017 | settings-dialog.tsx, settings.store.ts |
| Persistence | REQ-STORE-001 to REQ-STORE-015 | All adapters in adapters/ |
| User Interface | REQ-UI-001 to REQ-UI-019 | All components |
| Data Export | REQ-EXPORT-001 to REQ-EXPORT-007 | note-editor.tsx |
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2026-01-08 | System | Initial requirements documentation based on source code analysis |
- Block: A structured content unit (paragraph, heading, list item, etc.)
- Content Blocks: User-authored, immutable content
- Enrichment Blocks: AI-generated, replaceable content
- Category: A single classification assigned to a note
- Tag: A keyword label applied to notes (multiple per note)
- Adapter: An interface implementation for data persistence
- EARS: Easy Approach to Requirements Syntax
- Store: A Zustand state management store
- Hydration: Loading persisted data into application state
End of Requirements Document