refactor(bruno): reorganize file structure from bruno-yaml to flat bruno directory

- Move all files from bruno-yaml/* to bruno/*
- Maintains existing directory structure within categories
- Updates bruno/user/auth files with OAuth2 refresh token flow
- Updates bruno/user/profile files for user profile management
- Adds bruno/dashboard/ directory with dashboard API tests
- Preserves all existing test scenarios and OpenCollection YAML format
- No functional changes - file reorganization only

bruno/devices/koreader/Get Book Metadata.yml

@@ -0,0 +1,92 @@
+info:
+  name: Get Book Metadata
+  type: http
+  seq: 8
+
+http:
+  method: GET
+  url: '{{base_url}}/api/sync/koreader/metadata/{{book_uuid}}'
+  auth: inherit
+
+docs: |-
+  ## Get KOReader Book Metadata
+
+  Retrieves metadata for a specific book from the server.
+
+  **Method:** GET
+
+  **Endpoint:** /api/sync/koreader/metadata/:book_uuid
+
+  **Authentication:** Bearer token
+
+  **Path Parameters:**
+  - `book_uuid` (string): SHA-256 based book identifier
+
+  **Response:**
+  - `uuid` (string): Book UUID (SHA-256)
+  - `title` (string): Book title
+  - `authors` (array): Author names
+  - `series` (string, optional): Series name
+  - `series_index` (number, optional): Position in series
+  - `publisher` (string, optional): Publisher name
+  - `publication_date` (string, optional): Release date
+  - `language` (string, optional): ISO 639-1 language code
+  - `description` (string, optional): Book description
+  - `cover_url` (string, optional): Cover image URL
+  - `cover_thumbnail_url` (string, optional): Thumbnail URL
+  - `identifiers` (object): Various identifiers
+    - `isbn` (string, optional): ISBN-13
+    - `asin` (string, optional): Amazon ASIN
+    - `goodreads` (string, optional): Goodreads ID
+    - `google_books` (string, optional): Google Books ID
+  - `metadata_sources` (array): Sources metadata was pulled from
+  - `last_synced` (string): Last metadata sync timestamp
+  - `file_metadata` (object):
+    - `file_size` (integer): File size in bytes
+    - `format` (string): File format (epub, pdf, mobi, etc.)
+    - `pages` (integer, optional): Page count
+    - `word_count` (integer, optional): Estimated words
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 404: Book not found
+
+  **Metadata Purpose:**
+  - Enrich book information on device
+  - Improve book organization
+  - Enable better search
+  - Support series sorting
+  - Provide cover images
+  - Link to external sources
+
+  **KOReader Usage:**
+  - Display in book info dialog
+  - Used for library sorting
+  - Shown in file browser
+  - Series grouping
+  - Cover display
+  - Search optimization
+
+  **SHA-256 Book ID:**
+  - Primary identifier in KOReader
+  - Universal across devices
+  - Format-independent
+  - Generated from file content
+  - Survives metadata changes
+
+  **Metadata Sources:**
+  - Google Books API
+  - Open Library
+  - Goodreads API
+  - ISBN database lookup
+  - Publisher metadata
+  - User-provided metadata
+
+  **Use Cases:**
+  - Initial book import
+  - Metadata refresh
+  - Cover image download
+  - Series organization
+  - Duplicate detection
+  - Library management

bruno/devices/koreader/Get Library.yml

@@ -0,0 +1,34 @@
+info:
+  name: KOReader Get Library
+  type: http
+  seq: 3
+http:
+  method: GET
+  url: '{{base_url}}/api/sync/koreader/library'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## KOReader Get Library
+  
+    Retrieves the user's library for KOReader sync operations.
+  
+    **Method:** GET
+  
+    **Endpoint:** /api/sync/koreader/library
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Response:**
+    - `library_sync` (object): Library sync data
+    - `total_books` (number): Total number of books
+    - `books` (array): Array of book objects
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/koreader/Get User Library for KOReader.yml

@@ -0,0 +1,103 @@
+info:
+  name: Get User Library for KOReader
+  type: http
+  seq: 9
+
+http:
+  method: GET
+  url: '{{base_url}}/api/sync/koreader/library'
+  auth: inherit
+
+docs: |-
+  ## Get KOReader User Library
+
+  Retrieves the user's book library for KOReader device sync.
+
+  **Method:** GET
+
+  **Endpoint:** /api/sync/koreader/library
+
+  **Authentication:** Bearer token (koreader_device_token)
+
+  **Query Parameters:**
+  None (returns entire library)
+
+  **Response:**
+  - `books` (array): Library items
+    - `uuid` (string): SHA-256 based book identifier
+    - `title` (string): Book title
+    - `authors` (array): Author names
+    - `series` (string, optional): Series name
+    - `series_index` (number, optional): Series position
+    - `publisher` (string, optional): Publisher
+    - `publication_date` (string, optional): Release date
+    - `language` (string, optional): Language code
+    - `description` (string, optional): Description
+    - `cover_url` (string, optional): Cover image URL
+    - `cover_thumbnail_url` (string, optional): Thumbnail URL
+    - `file_metadata` (object):
+      - `format` (string): File format
+      - `file_size` (integer): Size in bytes
+      - `pages` (integer, optional): Page count
+    - `progress` (object, optional): Reading progress
+      - `percentage` (number): Progress 0-100
+      - `last_read` (string): Last read timestamp
+      - `epubcfi` (string): Current position
+    - `annotations_count` (object, optional): Annotation stats
+      - `highlights` (integer): Highlight count
+      - `notes` (integer): Note count
+      - `bookmarks` (integer): Bookmark count
+  - `library_info` (object):
+    - `total_books` (integer): Total book count
+    - `last_sync` (string): Last library sync timestamp
+    - `has_updates` (boolean): Updates available
+  - `user_info` (object):
+    - `user_id` (string): User identifier
+    - `email` (string): Email (masked)
+    - `libraries` (array): Available library IDs
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 403: Device not approved
+
+  **Library Purpose for KOReader:**
+  - Discover books available for download
+  - Browse catalog on device
+  - Sync reading progress across books
+  - Download covers/metadata
+  - Series-based organization
+  - Cloud library access
+
+  **KOReader Device Features:**
+  - **OPDS catalog**: Native OPDS client
+  - **File browser**: See server books
+  - **Cloud download**: Download books on-demand
+  - **Metadata sync**: Automatic metadata fetching
+  - **Cover images**: Display in library view
+  - **Progress sync**: See progress across all books
+  - **Search**: Search library by title/author
+
+  **KOReader-Specific Features:**
+  - SHA-256 based book IDs
+  - Multi-format support (EPUB, FB2, PDF, DJVU, MOBI, etc.)
+  - Series sorting and grouping
+  - Language filtering
+  - Cover image caching
+  - Metadata for file browser enhancement
+  - Integration with KOReader's OPDS client
+
+  **Performance:**
+  - Typical response: 100-500KB for 100 books
+  - Processing time: 300ms-1s
+  - Cache duration: 5 minutes
+  - Pagination support for libraries >500 books
+
+  **Use Cases:**
+  - Initial device setup
+  - Library browsing on device
+  - Book download
+  - Metadata refresh
+  - Cover image sync
+  - Progress overview
+  - Series-based reading

bruno/devices/koreader/api.yml

@@ -0,0 +1,7 @@
+info:
+  name: Bookhoard KOReader Sync API
+  type: collection
+  seq: 1
+http:
+  method: POST
+  url: '"http://localhost:8765/api"'

bruno/devices/koreader/scenarios/Checkpoint Sync.yml

@@ -0,0 +1,123 @@
+info:
+  name: Checkpoint Sync
+  type: http
+  seq: 11
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      sync_mode: checkpoint
+      checkpoint_id: checkpoint-uuid
+      since_timestamp: '2026-01-30T19:00:00Z'
+      books:
+        - uuid: book-uuid-1
+          percentage: 0.45
+          chapter: 3
+        - uuid: book-uuid-2
+          percentage: 0.75
+          chapter: 8
+
+docs: |-
+  ## Checkpoint Sync
+
+  Incremental sync using checkpoint-based change tracking.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `sync_mode` (string): Must be `checkpoint`
+  - `checkpoint_id` (string): Unique checkpoint identifier
+  - `since_timestamp` (string): ISO 8601 timestamp for incremental sync
+  - `books` (array): Book progress items
+    - `uuid` (string): Book UUID
+    - `percentage` (number): Progress 0.0-1.0
+    - `chapter` (integer): Current chapter
+    - `epubcfi` (string, optional): Current position
+    - `modified_since` (boolean, optional): Whether modified since checkpoint
+
+  **Response:**
+  - `checkpoint_id` (string): Server checkpoint ID
+  - `checkpoint_timestamp` (string): Checkpoint creation time
+  - `processed` (integer): Books processed
+  - `changes_only` (boolean): Whether only changed items synced
+  - `next_checkpoint_id` (string): ID for next checkpoint sync
+  - `results` (array): Per-book results
+
+  **Status Codes:**
+  - 200: Checkpoint sync completed
+  - 401: Unauthorized
+  - 400: Invalid checkpoint or timestamp
+
+  **Checkpoint Sync Benefits:**
+  - **Incremental**: Only sync changed items
+  - **Efficient**: Smaller payloads
+  - **Fast**: Reduced processing time
+  - **Reliable**: Checkpoint-based tracking
+  - **Resumable**: Can continue from last checkpoint
+
+  **Checkpoint Mechanism:**
+  - Server tracks changes since checkpoint
+  - Client provides checkpoint ID or timestamp
+  - Only modified books returned/processed
+  - Checkpoint ID advances on each sync
+  - Supports large libraries efficiently
+
+  **Use Cases:**
+  - Large libraries (100+ books)
+  - Intermittent connectivity
+  - Bandwidth optimization
+  - Battery conservation
+  - Background sync
+  - Periodic sync (every 5-15 minutes)
+
+  **Checkpoint Lifecycle:**
+  1. Initial sync: No checkpoint (full sync)
+  2. Server returns checkpoint_id
+  3. Next sync: Client sends checkpoint_id
+  4. Server processes only changes
+  5. New checkpoint_id returned
+  6. Repeat from step 3
+
+  **Sync Optimization:**
+  - Only books with progress changes
+  - Skips unmodified books
+  - Delta transfer
+  - Compression for large payloads
+  - Batch processing
+
+  **Failure Handling:**
+  - Checkpoint ID preserved on failure
+  - Retry with same checkpoint
+  - Full sync if checkpoint expired
+  - Checkpoint validity: 24 hours
+  - Auto-fallback to full sync
+
+  **Performance:**
+  - Small changes (1-10 books): 100-300ms
+  - Medium changes (10-50 books): 300ms-1s
+  - Large changes (50-100 books): 1-3s
+  - Typical: 5-10x faster than full sync
+
+  **When to Use:**
+  - Default sync mode for most users
+  - Periodic background sync
+  - Large library management
+  - Mobile/network-constrained environments
+  - Battery-powered devices
+
+  **Configuration:**
+  - Checkpoint expiration: 24 hours
+  - Max history: 100 checkpoints
+  - Auto-cleanup of old checkpoints
+  - Configurable sync interval

bruno/devices/koreader/scenarios/Immediate Sync - Page Turn.yml

@@ -0,0 +1,105 @@
+info:
+  name: Immediate Sync - Page Turn
+  type: http
+  seq: 10
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      sync_mode: immediate
+      books:
+        - uuid: book-uuid
+          percentage: 0.45678
+          chapter: 3
+          timestamp: '2026-01-30T20:00:00Z'
+
+docs: |-
+  ## Immediate Sync - Page Turn
+
+  Real-time progress sync triggered immediately on page turn.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `sync_mode` (string): Must be `immediate`
+  - `books` (array): Current book progress
+    - `uuid` (string): Book UUID
+    - `percentage` (number): Precise progress (0.45678 = 45.678%)
+    - `chapter` (integer): Current chapter
+    - `timestamp` (string): ISO 8601 timestamp
+    - `epubcfi` (string, optional): Current position
+    - `page` (integer, optional): Current page
+
+  **Response:**
+  - `synced` (boolean): Immediate sync status
+  - `timestamp` (string): Server timestamp
+  - `next_sync_suggested` (string): Suggested next sync time
+
+  **Status Codes:**
+  - 200: Sync queued
+  - 202: Accepted for processing
+  - 401: Unauthorized
+  - 429: Too many immediate sync requests (rate limited)
+
+  **Immediate Sync Mode:**
+  - **Purpose**: Real-time progress updates
+  - **Trigger**: Every page turn (configurable)
+  - **Priority**: High priority processing
+  - **Latency**: <100ms typical
+  - **Best effort**: May be queued under load
+
+  **Rate Limiting:**
+  - Max 60 requests per minute per device
+  - Throttled after limit reached
+  - Suggests switching to periodic sync
+  - Prevents server overload
+
+  **Use Cases:**
+  - Real-time multi-device reading
+  - Live progress sharing
+  - Instant position backup
+  - Critical reading points
+  - Test/profiling mode
+
+  **Performance:**
+  - Ultra-fast sync
+  - Minimal payload
+  - Optimized for speed
+  - Async processing
+  - No confirmation wait
+
+  **Battery Considerations:**
+  - More frequent network use
+  - Higher battery consumption
+  - WiFi recommended
+  - Can reduce sync frequency in settings
+
+  **Configuration:**
+  - Can enable/disable per device
+  - Adjustable frequency (every page, every N pages)
+  - Automatic fallback to periodic sync on error
+  - Respects device power-save mode
+
+  **When to Use:**
+  - Critical reading sessions
+  - Multi-device concurrent reading
+  - Research and study
+  - Testing sync functionality
+  - When power source available
+
+  **When NOT to Use:**
+  - Battery conservation needed
+  - Unstable network
+  - Extended reading sessions
+  - Background sync preferred

bruno/devices/koreader/scenarios/Sync Annotations (Per-Book SHA-256).yml

@@ -0,0 +1,44 @@
+info:
+  name: KOReader Sync Annotations - Per-Book SHA-256
+  type: http
+  seq: 4
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/koreader/sync/bookmarks'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"book_uuid\": \"{{book_uuid"
+  headers:
+  - key: Authorization
+    value: Bearer {{koreader_device_token
+
+docs: |-
+  ## KOReader Sync Annotations - Per-Book SHA-256
+  
+    Synchronizes annotations (highlights) from KOReader with per-annotation SHA-256 hashes for multi-book sync.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/koreader/sync/bookmarks
+  
+    **Authentication:** Bearer token (KOReader device token)
+  
+    **Request Body:**
+    - `book_uuid` (string): Primary book UUID
+    - `highlights` (array): Array of highlight objects
+      - `text` (string): Highlighted text
+      - `pos0`, `pos1` (string): EPUB CFI positions
+      - `color` (string): Highlight color (hex)
+      - `page` (number): Page number
+      - `book_sha256` (string): SHA-256 hash for this specific book
+  
+    **Response:**
+    - `highlights_synced` (number): Number of highlights synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Each highlight can include its own book_sha256, allowing annotations from multiple books in a single request.

bruno/devices/koreader/scenarios/Sync Bookmarks (SHA-256).yml

@@ -0,0 +1,40 @@
+info:
+  name: KOReader Sync Bookmarks - SHA-256
+  type: http
+  seq: 3
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/koreader/sync/bookmarks'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"book_sha256\": \"{{book_sha256"
+  headers:
+  - key: Authorization
+    value: Bearer {{koreader_device_token
+
+docs: |-
+  ## KOReader Sync Bookmarks - SHA-256
+  
+    Synchronizes bookmarks, notes, and highlights from KOReader using SHA-256 hash for book identification.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/koreader/sync/bookmarks
+  
+    **Authentication:** Bearer token (KOReader device token)
+  
+    **Request Body:**
+    - `book_sha256` (string): SHA-256 hash of book file
+    - `bookmarks` (array): Array of bookmarks
+    - `notes` (array): Array of notes
+    - `highlights` (array): Array of highlights
+  
+    **Response:**
+    - `sync_status` (string): Sync status
+    - `total_synced` (number): Total items synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/koreader/scenarios/Sync Bookmarks.yml

@@ -0,0 +1,105 @@
+info:
+  name: Sync Bookmarks
+  type: http
+  seq: 5
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/bookmarks'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid
+          bookmarks:
+            - chapter: 3
+              datetime: '2026-01-30T19:55:00Z'
+              notes: Marked this chapter as important
+              pos0: 'epubcfi(/6/4/2:15)'
+              pos1: 'epubcfi(/6/4/2:20)'
+              page: 45
+              text: Important passage
+              type: bookmark
+
+docs: |-
+  ## Sync KOReader Bookmarks
+
+  Synchronizes bookmarks separately from progress for KOReader.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/bookmarks
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with bookmarks
+    - `uuid` (string): Book UUID
+    - `bookmarks` (array): Bookmark items
+      - `chapter` (integer): Chapter number
+      - `datetime` (string): ISO 8601 timestamp
+      - `notes` (string): Bookmark description
+      - `pos0` (string): EPUB CFI start position
+      - `pos1` (string): EPUB CFI end position
+      - `page` (integer): Page number
+      - `text` (string): Displayed text
+      - `type` (string): `bookmark`, `highlight`, or `note`
+
+  **Response:**
+  - `synced` (integer): Number of bookmarks synced
+  - `duplicates_skipped` (integer): Duplicate bookmarks skipped
+  - `results` (array): Per-bookmark results
+  - `timestamp` (string): Sync timestamp
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 400: Invalid data
+
+  **Dedicated Bookmark Endpoint:**
+  - **Purpose**: Sync bookmarks independently
+  - **Use case**: More frequent bookmark updates
+  - **Advantage**: Separate from progress sync
+  - **Efficiency**: Smaller payloads
+
+  **KOReader Bookmark Features:**
+  - Chapter-based organization
+  - Quick navigation markers
+  - Hierarchical bookmarks (via plugins)
+  - Custom bookmark titles
+  - Date/time tracking
+  - EPUB CFI precision
+
+  **Bookmark Types in KOReader:**
+  - **Location bookmarks**: Quick navigation points
+  - **Chapter marks**: Auto-generated chapter markers
+  - **Progress bookmarks**: Last read positions
+  - **Custom bookmarks**: User-created markers
+  - **Search bookmarks**: Saved search results
+
+  **Sync Behavior:**
+  - Duplicate detection by position + text
+  - Most recent wins on conflicts
+  - Chapter order preserved
+  - Auto-generated vs manual bookmarks differentiated
+  - Merge with existing bookmarks
+
+  **KOReader Device Integration:**
+  - Created via "Add bookmark" menu
+  - Shown in "Bookmarks" panel
+  - Quick access via "Go to bookmark"
+  - Exportable to JSON
+  - Can be edited/deleted
+
+  **Use Cases:**
+  - Quick navigation aids
+  - Chapter markers
+  - Important passages
+  - Reading progress points
+  - Study session markers

bruno/devices/koreader/scenarios/Sync Highlights.yml

@@ -0,0 +1,110 @@
+info:
+  name: Sync Highlights
+  type: http
+  seq: 6
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/highlights'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid
+          highlights:
+            - datetime: '2026-01-30T19:50:00Z'
+              text: Important quote from book
+              chapter: 4
+              pos0: 'epubcfi(/6/4/2:20)'
+              pos1: 'epubcfi(/6/4/2:30)'
+              page_start: 78
+              page_end: 79
+
+docs: |-
+  ## Sync KOReader Highlights
+
+  Synchronizes text highlights separately from other annotations.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/highlights
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with highlights
+    - `uuid` (string): Book UUID
+    - `highlights` (array): Highlight items
+      - `datetime` (string): Creation timestamp
+      - `text` (string): Highlighted text content
+      - `chapter` (integer): Chapter number
+      - `pos0` (string): EPUB CFI start position
+      - `pos1` (string): EPUB CFI end position
+      - `page_start` (integer): Start page
+      - `page_end` (integer): End page
+      - `color` (string, optional): Color name or hex
+      - `note` (string, optional): Attached note
+
+  **Response:**
+  - `synced` (integer): Highlights synced
+  - `duplicates_skipped` (integer): Duplicates found
+  - `with_notes` (integer): Highlights that have notes attached
+  - `timestamp` (string): Sync timestamp
+
+  **KOReader Highlight Features:**
+  - Precise text selection (EPUB CFI)
+  - Custom color support (via plugins)
+  - Multi-page highlights
+  - Chapter references
+  - Timestamps for sorting
+  - Attached notes support
+  - Full text preservation
+
+  **Highlight Colors (via plugins):**
+  - Yellow (default): General highlighting
+  - Green: Important concepts
+  - Blue: Key information
+  - Red/pink: Critical content
+  - Orange: Interesting quotes
+  - Custom RGB colors available
+
+  **EPUB CFI Advantages:**
+  - Precise start/end positions
+  - Works across font size changes
+  - Survives text reflow
+  - Device-independent
+  - Standardized format
+
+  **Dedicated Highlight Endpoint:**
+  - **Separate from progress**: Sync highlights independently
+  - **Smaller payload**: Just highlights, no progress
+  - **More frequent**: Can sync highlights immediately
+  - **Focused**: Single-purpose endpoint
+
+  **Sync Behavior:**
+  - Exact text matching for duplicates
+  - Position-based conflict resolution
+  - Color preservation across devices
+  - Note attachments preserved
+  - Order maintained by position
+
+  **KOReader Device Features:**
+  - Created via long-press or selection
+  - Color picker available
+  - Can add notes immediately
+  - Shows in "Highlights" panel
+  - Exportable to Evernote, etc.
+  - Searchable by content
+
+  **Use Cases:**
+  - Study and research
+  - Content curation
+  - Quote collection
+  - Academic work
+  - Sharing insights

bruno/devices/koreader/scenarios/Sync Notes.yml

@@ -0,0 +1,108 @@
+info:
+  name: Sync Notes
+  type: http
+  seq: 7
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/notes'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid
+          notes:
+            - datetime: '2026-01-30T19:52:00Z'
+              text: My personal note about this chapter
+              chapter: 4
+
+docs: |-
+  ## Sync KOReader Notes
+
+  Synchronizes user notes separately from highlights and bookmarks.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/notes
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with notes
+    - `uuid` (string): Book UUID
+    - `notes` (array): Note items
+      - `datetime` (string): Creation/modification timestamp
+      - `text` (string): Note content
+      - `chapter` (integer): Chapter number
+      - `pos0` (string, optional): Related EPUB CFI position
+      - `page` (integer, optional): Page number
+      - `highlighted_text` (string, optional): Related highlight
+
+  **Response:**
+  - `synced` (integer): Notes synced
+  - `duplicates_skipped` (integer): Duplicate notes found
+  - `attached_to_highlights` (integer): Notes linked to highlights
+  - `timestamp` (string): Sync timestamp
+
+  **KOReader Note Features:**
+  - Free-form text notes
+  - Can be standalone or attached to highlights
+  - Chapter-based organization
+  - Timestamped for sorting
+  - Markdown support (some versions)
+  - Longer form content
+  - No character limit
+
+  **Note Types:**
+  - **Standalone notes**: Independent notes about chapter/section
+  - **Attached notes**: Notes attached to specific highlights
+  - **Chapter notes**: Notes about entire chapter
+  - **Book notes**: General notes about the book
+
+  **Dedicated Notes Endpoint:**
+  - **Separate sync**: Notes sync independently
+  - **Flexible**: Not tied to highlights
+  - **Efficient**: Smaller, focused payload
+  - **Immediate**: Can sync right after note creation
+
+  **Attached Notes:**
+  - Linked to specific highlight
+  - Shares highlight's position
+  - Shown together with highlight
+  - Deleted when highlight deleted (optional)
+  - Color matches highlight
+
+  **Sync Behavior:**
+  - Text-based duplicate detection
+  - Time-based conflict resolution
+  - Chapter organization preserved
+  - Markdown formatting preserved
+  - Attachment links maintained
+
+  **KOReader Device Integration:**
+  - Created via "Add note" option
+  - Edited in note editor
+  - Shown in "Notes" panel
+  - Can be organized by chapter
+  - Export functionality available
+  - Search support
+
+  **Advanced Features:**
+  - **Markdown**: Bold, italic, lists (some versions)
+  - **Tags**: User-defined tags (via plugins)
+  - **Links**: Internal/external links
+  - **Formatting**: Rich text in newer versions
+
+  **Use Cases:**
+  - Study notes
+  - Personal reflections
+  - Academic annotations
+  - Research insights
+  - Book club discussion prep
+  - Knowledge management

bruno/devices/koreader/scenarios/Sync Progress (SHA-256 Only).yml

@@ -0,0 +1,47 @@
+info:
+  name: KOReader Sync Progress - SHA-256 Only
+  type: http
+  seq: 2
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/koreader/sync/progress'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"sync_mode\": \"immediate\",\n    \"books\": [\n      {\n \
+      \       \"sha256\": \"{{book_sha256"
+  headers:
+  - key: Authorization
+    value: Bearer {{koreader_device_token
+
+docs: |-
+  ## KOReader Sync Progress - SHA-256 Only
+  
+    Synchronizes reading progress using only SHA-256 hash for book identification (when UUID is not available).
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/koreader/sync/progress
+  
+    **Authentication:** Bearer token (KOReader device token)
+  
+    **Request Body:**
+    - `sync_mode` (string): Sync mode (immediate, deferred)
+    - `books` (array): Array of book progress objects
+      - `sha256` (string): SHA-256 hash of book file
+      - `file_path` (string): Path to book file
+      - `percentage` (number): Progress percentage
+      - `page` (number): Current page
+      - `total_pages` (number): Total pages
+  
+    **Response:**
+    - `sync_status` (string): Sync status
+    - `books_synced` (number): Number of books synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 202: Accepted
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Use this when book UUID is not available, falling back to SHA-256 hash for identification.

bruno/devices/koreader/scenarios/Sync Progress (SHA-256).yml

@@ -0,0 +1,51 @@
+info:
+  name: KOReader Sync Progress - SHA-256
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/koreader/sync/progress'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"sync_mode\": \"immediate\",\n    \"books\": [\n      {\n \
+      \       \"uuid\": \"{{book_uuid"
+  headers:
+  - key: Authorization
+    value: Bearer {{koreader_device_token
+
+docs: |-
+  ## KOReader Sync Progress - SHA-256
+  
+    Synchronizes reading progress from a KOReader device using SHA-256 book hash for identification.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/koreader/sync/progress
+  
+    **Authentication:** Bearer token (KOReader device token)
+  
+    **Request Body:**
+    - `sync_mode` (string): Sync mode (immediate, deferred)
+    - `books` (array): Array of book progress objects
+      - `uuid` (string): Book UUID
+      - `sha256` (string): SHA-256 hash of book file for identification
+      - `file_path` (string): Path to book file on device
+      - `percentage` (number): Progress percentage (0-1)
+      - `chapter` (number): Current chapter
+      - `page` (number): Current page
+      - `total_pages` (number): Total pages
+      - `epubcfi` (string): EPUB location
+      - `last_read` (string): ISO 8601 timestamp
+      - `title` (string): Book title
+      - `authors` (array): List of authors
+  
+    **Response:**
+    - `sync_status` (string): Sync status
+    - `books_synced` (number): Number of books synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 202: Accepted - processing
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/koreader/scenarios/Sync Progress - Multiple Books.yml

@@ -0,0 +1,90 @@
+info:
+  name: Sync Progress - Multiple Books
+  type: http
+  seq: 2
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-1-uuid
+          title: Book One
+          authors:
+            - Author One
+          progress: 0.25
+          percentage: 0.25
+          last_read: '2026-01-30T19:00:00Z'
+          chapter: 1
+          epubcfi: 'epubcfi(/6/4/2:10)'
+        - uuid: book-2-uuid
+          title: Book Two
+          authors:
+            - Author Two
+          progress: 0.75
+          percentage: 0.75
+          last_read: '2026-01-30T20:00:00Z'
+          chapter: 8
+          epubcfi: 'epubcfi(/6/4/2:50)'
+
+docs: |-
+  ## Sync KOReader Progress - Multiple Books
+
+  Synchronizes reading progress for multiple books in a single request.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Multiple book progress items
+    - Each item contains: uuid, title, authors, progress, percentage, last_read, chapter, epubcfi
+
+  **Response:**
+  - `synced` (integer): Number of books successfully synced
+  - `failed` (integer): Number of books that failed
+  - `results` (array): Per-book sync results
+  - `timestamp` (string): Sync timestamp
+
+  **Status Codes:**
+  - 200: Batch sync completed
+  - 207: Multi-status (partial success)
+  - 401: Unauthorized
+  - 413: Payload too large
+
+  **Batch Sync Advantages:**
+  - Efficient sync of entire library
+  - Single HTTP request for multiple books
+  - Faster periodic sync
+  - Reduced battery usage vs individual syncs
+  - Better for batch processing
+
+  **KOReader Batch Behavior:**
+  - Triggered on device wake from sleep
+  - Occurs during "Sync now" operation
+  - Runs on WiFi connection
+  - Limited to 100 books per request
+  - Automatic retry on failed books
+
+  **Performance:**
+  - Small batch (2-10 books): 200-500ms
+  - Medium batch (10-50 books): 500ms-2s
+  - Large batch (50-100 books): 2-5s
+  - Timeout: 30 seconds
+
+  **Use Cases:**
+  - Device initialization sync
+  - Periodic background sync
+  - Post-offline catch-up sync
+  - Library-wide progress update
+  - Before firmware update

bruno/devices/koreader/scenarios/Sync Progress - Single Book.yml

@@ -0,0 +1,92 @@
+info:
+  name: Sync Progress - Single Book
+  type: http
+  seq: 1
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid-here
+          title: Book Title
+          authors:
+            - Author Name
+          progress: 0.45
+          percentage: 0.45
+          last_read: '2026-01-30T20:00:00Z'
+          chapter: 3
+          epubcfi: 'epubcfi(/6/4/2:15)'
+          character: 15432
+
+docs: |-
+  ## Sync KOReader Progress - Single Book
+
+  Synchronizes reading progress for a single book from KOReader device.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token (koreader_device_token)
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID for multi-library setups
+  - `books` (array): Array with single book progress
+    - `uuid` (string): Unique book identifier (often SHA-256 hash)
+    - `title` (string): Book title
+    - `authors` (array): List of authors
+    - `progress` (number): Progress decimal (0.0 to 1.0)
+    - `percentage` (number): Progress percentage (0.45 = 45%)
+    - `last_read` (string): ISO 8601 timestamp of last read
+    - `chapter` (integer): Current chapter number
+    - `epubcfi` (string): EPUB Canonical Fragment Identifier
+    - `character` (integer): Character position in book
+    - `page` (integer, optional): Current page number
+
+  **Response:**
+  - `synced` (integer): Number of books synced
+  - `timestamp` (string): Server sync timestamp
+  - `books` (array): Sync results
+    - `uuid` (string): Book UUID
+    - `status` (string): `synced`, `updated`, `skipped`
+    - `server_progress` (object): Server-side progress data
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 400: Invalid request format
+
+  **KOReader Progress Tracking:**
+  - SHA-256 based book identification (universal across devices)
+  - EPUB CFI for precise location (standard format)
+  - Chapter-based navigation
+  - Character-level precision
+  - Supports EPUB, FB2, PDF, DJVU, MOBI formats
+
+  **EPUB CFI Format:**
+  - Standardized location format for EPUBs
+  - Example: `epubcfi(/6/4/2:15)`
+  - Identifies exact position even after reflow
+  - Works across different devices/apps
+  - Preserved after file modifications
+
+  **Book Identification:**
+  - Primary: SHA-256 hash of book file
+  - Universal: Same book = same UUID across devices
+  - Format-agnostic: Works for any supported format
+  - Case-sensitive: Hash must match exactly
+
+  **Use Cases:**
+  - Real-time page turn sync
+  - Progress backup
+  - Cross-device continuity
+  - Reading time tracking
+  - Chapter completion detection

bruno/devices/koreader/scenarios/Sync Progress - With Bookmarks.yml

@@ -0,0 +1,106 @@
+info:
+  name: Sync Progress - With Bookmarks
+  type: http
+  seq: 3
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid-here
+          title: Book Title
+          authors:
+            - Author Name
+          progress: 0.45
+          percentage: 0.45
+          last_read: '2026-01-30T20:00:00Z'
+          bookmarks:
+            - chapter: 3
+              datetime: '2026-01-30T19:55:00Z'
+              notes: highlighted text
+              pos0: 'epubcfi(/6/4/2:15)'
+              pos1: 'epubcfi(/6/4/2:20)'
+              page: 45
+              text: highlighted text excerpt
+              type: highlight
+
+docs: |-
+  ## Sync Progress with Bookmarks
+
+  Synchronizes reading progress with bookmarks/highlights from KOReader.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with progress and bookmarks
+    - `uuid`, `title`, `authors`, `progress`, etc.
+    - `bookmarks` (array): Bookmark items
+      - `chapter` (integer): Chapter number
+      - `datetime` (string): ISO 8601 timestamp
+      - `notes` (string): Note content or highlighted text
+      - `pos0` (string): EPUB CFI start position
+      - `pos1` (string): EPUB CFI end position
+      - `page` (integer): Page number
+      - `text` (string): Displayed text excerpt
+      - `type` (string): `highlight`, `bookmark`, or `note`
+
+  **Response:**
+  - `progress_synced` (integer): Progress items synced
+  - `bookmarks_synced` (integer): Bookmark items synced
+  - `highlights_synced` (integer): Highlight count
+  - `timestamp` (string): Sync timestamp
+
+  **KOReader Bookmark Types:**
+  - **highlight**: Selected text passages
+  - **bookmark**: Location markers
+  - **note**: Text annotations (can be attached to highlights)
+
+  **KOReader Highlight Features:**
+  - Custom colors (via color extensions)
+  - Multi-color support
+  - Precise EPUB CFI positioning
+  - Chapter-based organization
+  - Text excerpts preserved
+  - Date/time stamped
+  - Page number tracking
+
+  **EPUB CFI in Bookmarks:**
+  - `pos0`: Start position (highlight start)
+  - `pos1`: End position (highlight end)
+  - Exact text selection boundaries
+  - Survives text reflow
+  - Works across different font sizes
+
+  **Sync Behavior:**
+  - Duplicate detection by text + position
+  - Most recent edit wins
+  - Chapter references maintained
+  - Order preserved from device
+  - Merges with existing server bookmarks
+
+  **KOReader Device Integration:**
+  - Created in KOReader highlight interface
+  - Shows in "Bookmarks" menu
+  - Can be edited/deleted on device
+  - Exportable to JSON/XML
+  - Searchable by content
+
+  **Use Cases:**
+  - Study and research
+  - Content review
+  - Passage tracking
+  - Quick navigation
+  - Cross-device bookmark access

bruno/devices/koreader/scenarios/Sync Progress - With Highlights and Notes.yml

@@ -0,0 +1,117 @@
+info:
+  name: Sync Progress - With Highlights and Notes
+  type: http
+  seq: 4
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid-here
+          title: Book Title
+          authors:
+            - Author Name
+          progress: 0.6
+          percentage: 0.6
+          last_read: '2026-01-30T20:00:00Z'
+          highlights:
+            - datetime: '2026-01-30T19:50:00Z'
+              text: Important passage
+              chapter: 4
+              pos0: 'epubcfi(/6/4/2:20)'
+              pos1: 'epubcfi(/6/4/2:30)'
+              page_start: 78
+              page_end: 79
+          notes:
+            - datetime: '2026-01-30T19:52:00Z'
+              text: My note about this chapter
+              chapter: 4
+
+docs: |-
+  ## Sync Progress with Highlights and Notes
+
+  Synchronizes reading progress with separate highlights and notes arrays.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with progress and annotations
+    - `uuid`, `title`, `authors`, `progress`, `percentage`, `last_read`
+    - `highlights` (array): Text highlights
+      - `datetime` (string): Creation timestamp
+      - `text` (string): Highlighted text content
+      - `chapter` (integer): Chapter number
+      - `pos0` (string): EPUB CFI start
+      - `pos1` (string): EPUB CFI end
+      - `page_start` (integer): Start page
+      - `page_end` (integer): End page
+      - `color` (string, optional): Highlight color
+    - `notes` (array): Notes
+      - `datetime` (string): Creation timestamp
+      - `text` (string): Note content
+      - `chapter` (integer): Chapter number
+      - `pos0` (string, optional): Related position
+
+  **Response:**
+  - `progress_synced` (boolean): Progress sync status
+  - `highlights_synced` (integer): Highlights synced
+  - `notes_synced` (integer): Notes synced
+  - `conflicts_resolved` (integer): Conflict count
+  - `timestamp` (string): Sync timestamp
+
+  **KOReader Annotation Model:**
+  - **Separate arrays**: Highlights and notes stored separately
+  - **Linked**: Notes can reference highlights
+  - **Rich metadata**: Timestamps, positions, page numbers
+  - **Flexible**: Supports complex annotations
+
+  **Highlight Features:**
+  - Multi-color highlighting (via plugins)
+  - Precise text selection with EPUB CFI
+  - Page range tracking
+  - Chapter references
+  - Timestamps for sorting
+  - Full text preserved
+
+  **Note Features:**
+  - Free-form text notes
+  - Can be standalone or attached
+  - Chapter-based organization
+  - Timestamped
+  - Longer form than highlights
+  - Support for markdown (some versions)
+
+  **Color Support (via plugins):**
+  - Yellow: Default highlight
+  - Green: Important passages
+  - Blue: Key concepts
+  - Red: Critical information
+  - Orange: Interesting quotes
+  - Custom colors available
+
+  **Sync Advantages:**
+  - Separation allows granular control
+  - Highlights sync without notes
+  - Notes sync independently
+  - Better conflict resolution
+  - Efficient for large annotation sets
+
+  **Use Cases:**
+  - Academic research
+  - Study groups
+  - Content analysis
+  - Personal knowledge management
+  - Sharing insights

bruno/devices/koreader/scenarios/Sync Progress.yml

@@ -0,0 +1,53 @@
+info:
+  name: KOReader Sync Progress
+  type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"library_id\": null,\n    \"books\": [\n      {\n        \"\
+      uuid\": \"{{book_uuid"
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## KOReader Sync Progress
+  
+    Synchronizes reading progress from a KOReader device to the Bookhoard server.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/sync/koreader/progress
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Request Body:**
+    - `library_id` (string, optional): Library UUID
+    - `books` (array): Array of book progress objects
+      - `uuid` (string): Book UUID
+      - `title` (string): Book title
+      - `authors` (array): List of authors
+      - `progress` (number): Progress value
+      - `percentage` (number): Percentage complete (0-1)
+      - `last_read` (string): ISO 8601 timestamp
+      - `chapter` (number): Current chapter
+      - `epubcfi` (string): EPUB Canonical Fragment Identifier
+      - `page` (number): Current page
+      - `total_pages` (number): Total pages
+    - `sync_mode` (string): Sync mode (immediate, deferred)
+    - `device_info` (object): Device information
+      - `koreader_version` (string): KOReader version
+      - `device_model` (string): Device model identifier
+  
+    **Response:**
+    - `sync_status` (string): Sync status (accepted, processing)
+    - `books_synced` (number): Number of books synced
+  
+    **Status Codes:**
+    - 202: Accepted - sync queued
+    - 401: Unauthorized
+    - 500: Internal server error