Document the authentication decision reached for the Android client:
username/password login is primary (the app needs the user-JWT API
surface that device tokens cannot reach), with the app self-approving
its own device registration post-login so it still shows up on the
Devices page with sync attribution.
Add the Netflix-style QR pairing flow to the post-v1 roadmap with its
constraints: the QR grants a full login with zero typing; a typed-code
fallback covers phones with broken cameras; KOReader keeps its existing
flow (no typed codes there); and pairing must encode the configured
BASE_URL rather than a detected LAN IP so remote instances
(https://public.domain) work identically.
Verified against the Echo routes and handler structs, fixing drift that
would break API clients:
- login: response field is access_token, not token (AuthResponse struct)
- register status: status is only pending|approved; expiry is HTTP 410
(not a status value), approved responses are single-use, and pending
registrations do not survive server restarts
- visible libraries: endpoint is GET /api/libraries/visibility and
returns a top-level array of full library rows, not a wrapped object
- media items list: response is {"data": [...]}, library_id is optional,
limit defaults to 50 (max 1000), no total field; document the sort
parameter, the two response shapes, and raw-vs-resolved file paths
refresh and device-registration docs verified accurate; no changes.
Document the planned native Android client (bookhoard-app): product
vision, tech stack and rationale (Kotlin + Compose + Readium over
hybrid/Flutter/KMP alternatives), module architecture, offline-first
sync flow over the existing REST/WebSocket API, reader and comics/manga
UX, iOS posture, distribution and licensing, and a five-milestone
roadmap. The client is a thin, offline-first consumer of the server's
existing device registration, universal progress, annotation, and
conflict-resolution APIs — no server changes required.
New media-items/deleted_annotations.md for the list/restore/purge
endpoints; endpoint index updated. The KOReader protocol page documents
deleted_highlights/deleted_bookmarks on the progress push and the
deletion-propagation contract: keys learned only from server pulls,
explicit arrays only (never absence), tombstone convergence via the
metadata fetch, no resurrection from stale replays, and the web history
as the restore path.
Add koreader/resolve_book.md for GET /api/sync/koreader/resolve, list
the endpoint in the API reference, and describe the resolve-then-pull-
then-push linking flow in the KOReader protocol page — including why a
device pushing to bootstrap its identity creates progress conflicts for
books already mid-read from other sources.
Monolithic api-reference.md:
- New 'System Settings & Configuration' and 'Hash Conflicts' sections
(endpoints, examples, response shapes) with TOC entries
- Device Management: add the sidecar config/download endpoints
- Fix stale registration flow: correct auth_url path, drop phantom
device_id, add poll_interval/setup_instructions, status endpoint is
POST /api/devices/register/status, and sync_endpoints point at
/api/sync/koreader/*
- Mark PUT /api/libraries/scan-settings as legacy/superseded
- Repair Additional Resources and Collections links (dead
COLLECTIONS_API.md / KOBO*_SETUP.md / missing-guide references)
Split api-reference.md index:
- Quick links and sections for System (settings + config) and the
admin hash-conflict endpoints; device sidecar endpoints under Device
Management; browse + legacy scan-settings routes under Libraries
sync_bookmarks.md documented a request shape the handler never accepted.
- Document the real body: book_uuid/book_sha256 (either required,
SHA-256 is format-aware), plus separate bookmarks/notes/highlights
arrays using the shared KOReader annotation shape (pos0/pos1, page,
text, type, per-annotation book_sha256, dedup_key, percentage)
- Document color semantics from 178fb2e/dafcadd: KOReader palette
names map to web hex swatches at the boundary, echoes carry no color
so stored web colors survive round-trips, explicit colors are device
edits
- koreader-protocol.md: cross-link the bookmark shape/color/dedup
rules from the progress-sync field table
- New get_sidecar_config.md for GET /api/devices/:id/sidecar and
/sidecar/download: the .bookhoard.json config served to devices
(endpoints, books keyed by per-format SHA-256 with UUID fallback,
collections, format availability) used by the KOReader plugin to
self-configure
- register_device.md: correct the response — no device_id at
registration; auth_url is /devices/approve/:id (was the nonexistent
/devices/auth/confirm/:id); document poll_interval and
setup_instructions, and the approve-then-poll flow
- get_devices.md: fix the status endpoint path to
POST /api/devices/register/status (was /api/devices/auth/status)
Cover the admin API added in 03cb4c7 for duplicate-content decisions:
- GET /api/admin/hash-conflicts — pending conflict groups with member
items and per-item usage counts (progress, highlights, bookmarks,
notes, collections)
- POST /api/admin/hash-conflicts/:id/resolve — action=keep (merge child
rows into keep_uuid, delete losers) vs action=keep_all (dismiss);
JSON and form-encoded bodies, error codes including 409 for already
resolved
- When conflicts are created (startup backfill, rescans) and the
guarantee that files on disk are never deleted
The scattered scan-settings JSON routes are superseded by the new
admin-only /api/system/settings pair backed by the SettingsRegistry
(introduced in 885f6d8 / bc47450).
- Rewrite system/settings.md around GET/PUT /api/system/settings:
SettingEntry metadata shape (type, min/max, requires_restart,
category, group, is_default), type-aware validation rules, and the
full tunable-setting catalog (scanner, general, security, api, sync,
performance) with defaults, ranges, and restart requirements
- Note the legacy /api/libraries/scan-settings routes as back-compat
only (they now refresh the registry cache on write)
- Add system/config.md for GET/PUT /api/system/config: raw key/value
system configuration (e.g. base_url), including validation notes and
guidance to prefer the typed settings endpoint for registry keys
- sync-guide: only Web and KOReader are fully supported; move Kobo to
coming soon, drop fake Q2-Q4 2026 release dates for mobile/Kindle/
Remarkable, and describe the plugin + server-approval registration
flow instead of QR-code/URL approval
- sync-guide: remove cellular/mobile-app advice from battery and
best-practice sections, correct the Calibre compatibility FAQ, update
the changelog to reflect shipped vs. pending sync features, and fix
the license header (GPL-3.0, not MIT)
- user-guide: lead device setup with KOReader; mark the Kobo guide as
coming soon
- calibre-integration: OPDS client list no longer implies native Kobo
support
- auth overview: label the mobile-application token guidance as
'coming later' since no mobile apps exist yet
Native Kobo sync is implemented server-side but not yet supported on
real devices, so stop documenting it as a working feature.
- Rewrite kobo-setup.md as a coming-soon stub: point users to KOReader
(which runs on Kobo hardware) as the supported path today, and list
what native sync will deliver when released
- Add 'Coming Soon' status banners to the Kobo protocol spec, all five
Kobo endpoint docs, and both API references, noting the endpoints are
under active development and may change
- Tag the device shelf endpoints as pending native Kobo support
Bring the koreader protocol doc in line with the hash-sharing work:
- Request table: uuid is no longer required (it is absent on the first
sync of a newly downloaded book); document sha256 and file_path and
the resolution priority uuid -> sha256 -> file_path alias ->
title/author
- Note that SHA-256 matching is format-aware (media_items hash first,
media_item_formats fallback) so converted KEPUB/PDF downloads match
- Document the sha256 field returned by the metadata and library
endpoints
- Add a 'Book identification' section pointing current and future
clients (koreader, kobo, OPDS, device-link UI, mobile apps) at the
shared BookResolver as the single resolution path
Update the OPDS section of the API reference to reflect the now-working
catalog:
- Document the page/per_page parameters and that paging is driven by the
rel=next/previous/first/last links plus OpenSearch paging metadata.
- Refresh the example feed XML to show the pagination links, opensearch
namespace/elements, and standard Atom <title>/<author> elements.
- Document the search endpoint's two modes: OpenSearch description
(application/opensearchdescription+xml, no q) and results feed (with q),
with an example description document.
- Add comprehensive API documentation for tags_filter parameter
- Document fuzzy matching behavior with examples
- Add user guide for tag-based filtering
- Document backward compatibility with genre_filter
- Include examples of fuzzy matching ("Sci Fi" → "Science Fiction")
Provides complete documentation for the new tags filter feature,
including API reference and user-facing documentation.
Relates to IMPLEMENTATION_TAGS_FILTER.md Phase 7
Add comprehensive documentation for GET /api/saved-filters/:id endpoint
including Bruno API collection, developer API docs, user documentation,
and implementation plan with frontend integration phase.
Bruno API Collection (bruno/saved-filters/Get Saved Filter By ID.yml):
- New Bruno request file for GET /:id endpoint
- Includes comprehensive documentation with examples
- Documents all status codes (200, 400, 401, 404)
- Provides example curl commands and use cases
- Uses variable placeholders ({{base_url}}, {{filter_id}})
- Follows existing Bruno YAML patterns
API Documentation (docs/developer/api/saved-filters/index.md):
- Added GET /api/saved-filters/:id endpoint documentation
- Example request with UUID parameter
- Example response showing filter object structure
- Error responses documented (400, 401, 404)
- Use cases: Mobile apps, SPAs, editing, verification
User Documentation (docs/user/library-browsing.md):
- Updated "Loading Saved Filters" section
- Removed "feature coming soon" language
- Added step-by-step instructions for loading filters
- Added tips section with visual indicators
- Added "Managing Saved Filters" section
- Added "Common Use Cases" (genre, author, series)
- Emphasizes instant feedback (no page reload)
Implementation Plan (GET_SAVED_FILTER_BY_ID_IMPLEMENTATION.md):
- Added Phase 7: User Documentation Update
- Added Phase 8: Frontend Integration (bookshelf.ts)
- Shows loadFilter() implementation
- Hybrid Alpine.js + HTMX approach
- Maintains SSR-first principles
- API call on user interaction, not page load
- Populates hidden form fields
- Triggers HTMX to apply filter
- Updated Summary of Changes: 7 files, ~344 lines
- Updated Checklist with frontend and user docs tasks
- Added frontend testing tasks
SSR-First Compliance:
- Initial page load: Server renders everything (no API calls)
- User interaction only: API called when user clicks filter
- No async x-init data fetching
- Progressive enhancement maintained
Documentation Structure:
- Developer docs: API reference for integration
- User docs: Step-by-step usage instructions
- Bruno: API contract testing
- Implementation plan: Complete development guide
All documentation follows established patterns and includes examples.
Add comprehensive guide for Alpine.js SSR-first patterns in Bookhoard:
- Page classification system (Type 1: 80% SSR, Type 2: SSR+Interactive,
Type 3: 80% TypeScript)
- Alpine.js usage guidelines (UI state only, no data fetching in x-init)
- HTMX integration patterns
- When to use x-show vs CSS classes
- Form handling and validation
- Modal and dropdown patterns
- Component reusability with Alpine.data()
- Alpine.store for global state (book picker example)
This documentation helps developers maintain consistency across the
codebase
and make informed decisions about when to use Alpine.js vs vanilla
JavaScript
vs HTMX for different features.
Follows PROJECT_GUIDELINES.md documentation standards.
This commit adds comprehensive functionality for filtering collections by library,
improves WebSocket real-time updates with user activity detection, and adds
extensive test coverage.
## Core Features
### Collection Library Filter
- Added library_id parameter to media-items search API
- Collections can now be filtered by specific library
- Toggle UI component for enabling/disabling library filter
- Default state is "checked" when library_id is present
- Consistent behavior across partial and fuzzy search modes
### WebSocket Auto-Reload Mitigation
- Added user activity detection to prevent disruptive page reloads
- Checks if user is actively typing in INPUT/TEXTAREA/SELECT elements
- Skips auto-reload when user is interacting with form elements
- Toast notifications still show for awareness
- Prevents data loss during editing operations
## Implementation Changes
### Backend
- internal/database/queries.sql.go: Added library filter support to search queries
- internal/handlers/media.go: Enhanced search with library_id parameter validation
- internal/handlers/collections.go: Updated collection handlers with library filtering
- internal/sync/websocket.go: Improved broadcast mechanism with user-scoped updates
- internal/router/frontend.go: Pass libraryID to collection templates
### Frontend
- templates/collections.templ: Added library filter toggle UI component
- web/src/collections.ts: TypeScript implementation with WebSocket integration
- templates/collections_templ.go: Generated template code
### Testing
- cmd/server/tests/search_test.go: Added TestCollectionSearchLibraryFilter
- cmd/server/tests/websocket_test.go: Added TestWebSocketUserScopedBroadcast
- New helper functions for creating libraries and media items via API
- Comprehensive test coverage for library filtering and user-scoped broadcasts
## API Documentation Updates
### Bruno Tests (Comprehensive Documentation)
- bruno/collections/*: Added detailed API documentation for all collection endpoints
- bruno/devices/*: Added device management and sync API documentation
- bruno/devices/kobo/api.yml: Kobo-specific sync protocol docs
- bruno/devices/koreader/api.yml: KOReader-specific sync protocol docs
- bruno/opds/*: Added OPDS feed and download endpoint documentation
- bruno/library/browse-folders.yml: Library folder browsing API docs
### New Bruno Tests
- bruno/media-items/Search All Libraries.yml: Test search without library filter
- bruno/media-items/Search Specific Library.yml: Test search with library filter
- bruno/media-items/Search Invalid Library ID.yml: Test error handling
## Documentation
- docs/developer/api/media-items/search_media_items.md: Updated with library_id parameter
- IMPLEMENTATION_COLLECTION_FIX.md: Comprehensive implementation guide with test scenarios
## Testing
### Integration Tests
- Library filter tests verify correct filtering across multiple libraries
- Invalid library_id tests ensure proper error handling
- WebSocket tests verify user-scoped broadcast behavior
- User A no longer receives User B's collection updates
### Manual Testing Scenarios
- Open collection in multiple tabs - updates propagate correctly
- Type in search box while another tab adds books - no disruptive reload
- Add/remove books from collection - toast notifications appear
- Toggle library filter - results update dynamically
## Technical Details
- WebSocket broadcasts are now user-scoped for privacy
- Active element detection uses tagName and contenteditable attributes
- Library ID validation uses UUID format checking
- Progressive enhancement maintained - page works without JavaScript
- All changes follow PROJECT_GUIDELINES.md conventions
- TypeScript only for frontend logic
- TailwindCSS only for styling
- Procedural programming style throughout
## Breaking Changes
None - all changes are additive and backward compatible.
- Update validation from minutes (15-1440) to seconds (1-3600)
- Clarify behavior: real-time file watching with polling fallback
- Remove scheduler references from development docs
- Update migration notes for the new implementation
- Update API field from scan_frequency_minutes to scan_poll_interval_seconds
- Update database schema default value key
- Update Bruno API collection requests and documentation
- Update OpenAPI documentation examples and field descriptions
- Update endpoint path in Get Scan Settings Bruno collection file
- Update endpoint path in Update Scan Settings Bruno collection file
- Update endpoint path in API reference documentation
This corrects a typo in the API path where 'library' was singular instead of plural.
Add comprehensive testing documentation covering:
- Test email domain usage (@tests.bookhoard.internal)
- Standard test users and their credentials
- Test lifecycle and cleanup process
- How to write tests properly
- Running tests (make targets, specific tests)
- Test organization and helper functions
This helps developers understand the testing infrastructure and
prevents accidental data loss when running tests.
Add documentation for delete_user and reset_user_password endpoints.
Update update_profile to reflect consolidated endpoint. Remove obsolete
documentation for individual update operations. Add profile guide for
end-users. Update API_CONSOLIDATION_PLAN.md with implementation status.
Phase 13 - Documentation Updates
- Add complete API documentation for custom section builder
- Document all 14 filter fields with operators
- Include example use cases (Sci-Fi Favorites, High Rated, etc.)
- Document preview endpoint and collection creation
- Verify existing dashboard.md documentation is comprehensive
Part of Carousel Dashboard Plan completion
Updated Carousel Dashboard documentation to reflect finalized architecture decisions
and resolve discrepancies between plan and verification checklist.
## CAROUSEL_DASHBOARD_PLAN.md Changes
### Added Phase 4.5: Collections Preview Endpoint
- Documented why preview endpoint is required (web UI + mobile apps)
- Explained why client-side preview is a bad idea (download entire library,
code duplication, maintenance nightmare)
- Added full PreviewCollection handler implementation
- Added Bruno test specification
### Enhanced Phase 7: Router Registration & Config Setup
- Renamed from "Router Registration" to "Router Registration & Config Setup"
- Added Step 1: Update router.go Config struct with line numbers
- Added Step 2: Update main.go initialization with line numbers
- Added Step 3: Update test_helpers.go with line numbers
- Added explanation: Why both DashboardService AND DashboardHandler?
### Updated Phase 10.5.4: Collections Preview Endpoint
- Referenced Phase 4.5 (endpoint already implemented earlier)
- Clarified needed for web UI AND mobile apps
- Noted no additional work needed
### Added Phase 10.6: Implementation Checklist
- 30+ checklist items with file paths and verification commands
- Organized by layer (Database, Service, Handler, Router, Templates, TypeScript, Tests, Docs)
- Added Build & Verification section
- Added Timeline Estimate (20-26 hours)
- Added Post-Implementation Tasks
## CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md Changes
### Added Clarification Section (at top)
- Explained all discrepancies between plan and checklist
- Preview endpoint IS in plan (Phase 4.5)
- Custom Section Builder IS in plan (Phase 10.5.2 and 10.5.3)
- Service method names - Plan is correct
- Config struct - Documented with exact line numbers
- DashboardService vs DashboardHandler - Explained why both needed
### Updated Service Method Names (Section 3.2)
Changed to match plan's actual implementation:
- GetDashboardSections (not GetSectionItems)
- filterHiddenCollections (not filterHiddenSections)
- reorderCollections (not reorderSections)
- sortByPriority (new method)
- getUserCollectionItems (not getCollectionSections)
- getCollectionItemsByQueryType (renamed)
### Enhanced Config Verification (Section 6.4)
Added exact line numbers for all 3 files:
- internal/router/router.go lines 58-59
- cmd/server/main.go lines 123-124, 172-173
- cmd/server/tests/test_helpers.go lines 419-420, 458-459
### Updated Preview Endpoint Section (Section 6.3)
Added clear explanation of why endpoint is REQUIRED and why NOT client-side.
### Clarified Custom Section Builder (Sections 8.5, 9.4)
Both now explicitly state "IS in the plan (Phase 10.5)"
## docs/developer/api/dashboard.md Changes
Updated API documentation to match new unified collections architecture:
- Terminology: "smart sections" → "system collections"
- Field: `type: string` → `is_system: boolean`
- Field: `id` → `media_item_id` for books
- Request: `hidden_sections` → `hidden_collections`
- Request: `section_order` → `collection_order`
- Removed: "in-progress" and "unread" smart sections
- Added: Update Dashboard Preferences endpoint
- Added: Restore System Collection endpoint
- Updated: Example responses with new field names and types
- Updated: Error responses table
## Impact
These changes clarify:
1. Preview endpoint is required for both web UI custom section builder and mobile apps
2. Custom Section Builder IS a major feature in the plan (not missing)
3. Service method names use "collections" terminology consistently
4. Config struct updates are clearly documented with exact line numbers (3 files only)
5. Why both DashboardService AND DashboardHandler are needed in Config
All documentation now accurately reflects the finalized Carousel Dashboard architecture.
Major architectural improvements:
1. Add generic /api/dashboard/sections JSON endpoint
- Created internal/handlers/dashboard.go (new file)
- Created internal/router/dashboard.go (new file)
- Single source of truth for web UI, mobile apps, plugins
- Follows existing handler/router pattern
2. Update DashboardService to apply user preferences
- GetSectionItems() now accepts sectionOrder and hiddenSections
- filterHiddenSections() removes user's hidden sections
- reorderSections() applies user's custom order
- Ensures consistent behavior across all clients
3. Separate concerns properly
- API handlers in internal/handlers/dashboard.go
- SSR routes remain in internal/router/frontend.go
- Both use same DashboardService (single source of truth)
4. Reorganize implementation phases
- Phase 1-3: Database, service, queries
- Phase 4-6: Handler, router, frontend routes
- Phase 7-9: Templates and settings
- Phase 10-11: TypeScript modules
- Phase 12-13: Documentation and testing
5. Add documentation
- docs/developer/api/dashboard.md (API reference)
- docs/user/dashboard.md (user guide)
6. Bruno tests already exist
- bruno/dashboard/ has 5 comprehensive test files
- Three-context testing (no user, user, admin)
- No additional tests needed
Benefits:
- Uniform dashboard across web, mobile, plugins
- Single source of truth (no duplicate logic)
- User preferences respected by all clients
- Follows established project patterns
- Comprehensive test coverage
Timeline: Updated to reflect 13 phases (19-25 days total with TypeScript)
Clean up API documentation files by removing Phase X references:
Remove 'API Explorer will be inserted here in Phase X' placeholders from:
- 70+ API endpoint documentation files
- Authentication endpoints (login, logout, register, refresh)
- User endpoints (profile, settings, password)
- Device endpoints (registration, sync, shelves)
- Library endpoints (CRUD, folders, visibility)
- Media endpoints (items, progress, highlights, notes)
- Admin endpoints (users, analytics)
- Sync endpoints (Kobo, KOReader)
- OPDS endpoints
- Scanner endpoints
- Queue endpoints
These placeholders were from planning documents and have no meaning
to API consumers. The documentation is now clean and ready for use.
- Update api-reference.md with new endpoint paths
- Update api-reference.md Books API section → Media Items API section
- Update index.md Books API link → Media Items API
- Update get_shelf.md cover_url reference from /api/books/ to /api/media-items/
- Add comprehensive documentation for bulk delete endpoint
- Add comprehensive documentation for bulk update endpoint
- Add comprehensive documentation for download endpoint
- Document all request/response fields with correct names
- Include examples and error codes
- Add notes on tag normalization and partial success
- Fix TestUpdateDevice: Use correct JSON field name and handle float64 type
- Fix TestRejectDeviceRegistration: Expect message response instead of boolean
- Update approve device docs: Add missing response fields
- Update reject device docs: Correct message text and format
- Update Bruno API: Fix example response for reject endpoint
Both integration tests now pass while maintaining API consistency.
System Settings API Documentation (new):
- docs/developer/api/system/settings.md
- Document GET /api/libraries/scan-settings endpoint
- Document PUT /api/libraries/scan-settings endpoint
- Include request/response examples
- Document validation rules and error codes
- Include migration notes from per-user to system-wide
User List API Documentation (update):
- docs/developer/api/admin/list_users.md
- Add max_devices field to response
- Add device_count field to response
- Include complete response field descriptions table
- Update example to show new fields
Documentation covers both the new system-wide scan settings feature
and the enhanced user list with device monitoring capabilities.
- Add POST /api/media-items prerequisite documentation
- Document 400 error for libraries without folders
- Update API reference with validation rules
- Include usage example showing proper setup order
Related: Media item validation changes
- Update api-reference.md with current endpoint list
- Update bulk_update_books.md with improved documentation
- Update scanner/overview.md to reference scan_library.md
- Add create_media_item.md for media item creation API
- Add delete_rating.md for rating deletion endpoint
- Add update_rating.md for rating update endpoint
- Rename ScanEbooks method to ScanLibrary to reflect generic media scanning
- Rename ScanEbooksRequest to ScanLibraryRequest
- Update route handlers in scanner.go and library.go
- Rename scan_ebooks.md to scan_library.md
- No breaking changes: API endpoint remains POST /api/scanner/scan
- sync_progress.md - POST /api/sync/koreader/progress
- get_metadata.md - GET /api/sync/koreader/metadata/:uuid
- get_library.md - GET /api/sync/koreader/library
- sync_bookmarks.md - POST /api/sync/koreader/bookmarks
KOReader device sync endpoints with device authentication
for progress, metadata, library, and bookmarks
- get_universal_progress.md - GET /api/progress/:id
- update_universal_progress.md - POST /api/progress/:id
- get_progress_history.md - GET /api/progress/:id/history
Documents device-agnostic (universal) reading progress tracking
that works across all devices (Kobo, KOReader, etc.)
- Add bulk_delete_books.md for POST /api/books/bulk-delete
- Add bulk_update_books.md for POST /api/books/bulk-update
- Includes tag/contributor normalization details
- Documents dual-field normalization behavior
- Add download_book.md for GET /api/books/:uuid/download
- Public endpoint with auth for non-public libraries
- Documents Content-Type headers for different formats
Completes books operations API section
john-okeefe