- Update README.md with simplified documentation links
- Update docs/API_REFERENCE.md formatting and structure
- Update docs/SYNC_USER_GUIDE.md with minor improvements
These updates reflect the reorganized documentation structure
and new configuration approach with defaults in docker-compose.yml.
- Add conversion service configuration with sensible defaults
- BOOKHOARD_CONVERSION_CACHE_DIR: /app/cache/kepub
- BOOKHOARD_CONVERSION_TOOL: /usr/bin/kepubify
- BOOKHOARD_CONVERSION_CACHE_TTL: 24h
- Add named volume for conversion cache
- Add rate limiting configuration with defaults
- TEST_MODE: false
- RATE_LIMIT_ENABLED: true
- REQUESTS_PER_MINUTE: 10
- Simplify .env.example to only required secrets (JWT_SECRET, DBPASS)
- Add section comments to docker-compose.yml for better organization
- Document optional overrides in .env.example comments
This change separates secrets (in .env) from operational configuration
(in docker-compose.yml), following security best practices while
maintaining flexibility for custom deployments.
- Remove internal development docs (phase tracking, implementation plans, security audits)
- Move DEVELOPMENT.md to docs/contributing/ for contributor guidance
- Move TROUBLESHOOTING.md from root to docs/ folder
- Add docs/INDEX.md as navigation hub for all documentation
- Clean up docs to focus on user/self-hoster facing content
This reorganization separates user-facing documentation from
internal contributor documentation, making the project more
approachable for self-hosters.
Complete the rename by updating:
- DeviceCatalogs struct field: BookmannUuid → BookhoardUuid (models.go)
- Generated queries: Update all references (queries.sql.go)
- Local variables: bookmannUUID → bookhoardUUID (kobo.go)
- Struct field access: catalog.BookmannUuid → catalog.BookhoardUuid
All "bookmann" and "BOOKMANN" references are now eliminated from the codebase.
Part of project rename to Bookhoard.
Changes:
- Update comments: "Bookmann UUID" → "Bookhoard UUID"
- Rename sidecar struct field: Bookmann → Bookhoard
- Update type names: SidecarBookmannConfig → SidecarBookhoardConfig
- Fix test database name in queue_test.go
- Fix uppercase env var examples in KOBO_SETUP.md
Internal Go variable names (BookmannUuid, bookmannUUID) left unchanged
as they're implementation details that don't affect functionality.
Part of project rename to Bookhoard.
Database changes:
- schema.sql: Update column name bookmann_uuid → bookhoard_uuid
- schema.sql: Update index names and example URLs
- queries.sql: Update all SQL queries to use bookhoard_uuid
- Update example configuration values
Part of project rename to Bookhoard.
Documentation updates:
- All docs/ files: Update project references
- Bruno API collection: Update collection name and tests
- Device setup guides: Update all examples
- Implementation plan: Update database schema examples
- README files: Update project references
Part of project rename to Bookhoard.
Test file updates:
- Update import paths in test files: bookmann/internal → bookhoard/internal
- Update test helper functions and references
- Update test comments and documentation
This is part 6 of the project rename to Bookhoard.
Documentation updates:
- Update README.md title and all references
- Update PROJECT_GUIDELINES.md title and guidelines
- Update all documentation files in docs/ directory
- Update device setup guides (Kobo, KOReader)
- Update API and architecture documentation
- Update completion summaries and progress reports
This is part 5 of the project rename to Bookhoard.
Bruno API test updates:
- Update test assertions: X-Bookmann-* → X-Bookhoard-*
- Update variable names and references in test scripts
- Update documentation and comments in API tests
This is part 4 of the project rename to Bookhoard.
Template changes:
- Update page titles: "Bookmann" → "Bookhoard"
- Update header branding and navigation text
- Regenerate compiled .go templates from .templ sources
- Update all UI references in HTML templates
This is part 3 of the project rename to Bookhoard.
Added 110 lines of safety guidelines to prevent future bugs:
New CRITICAL PROHIBITIONS:
- NEVER delete code without reading full context (20 lines before/after)
- NEVER make cascading fix-up edits without git diff review
- NEVER skip post-edit verification
New MANDATORY REQUIREMENTS:
- Post-Edit Verification (mandatory for all file modifications)
- Backup Before Large Changes
- Large Deletion Safety Pattern
New ERROR RECOVERY PROTOCOL:
- Immediate actions when mistakes occur
- Recovery examples with git commands
- Prevention learning points
New WORKFLOW CHECKLISTS:
- Error Recovery Protocol
- Phase Completion Verification
These guidelines address the critical bug where auth functions were
accidentally deleted during cleanup, preventing recurrence.
Added comprehensive documentation of Phases 1-3:
- Phase 1: Documentation cleanup details
- Phase 2: Dead code removal summary
- Phase 3: Test suite cleanup details
- Complete statistics and verification results
This document serves as a record of the legacy code cleanup
work completed in this session.
New test file with 5 test suites:
- TestMediaItemISBNNormalization (8 test cases)
- TestMediaItemISBNEdgeCases (3 test cases)
- TestMediaItemsPagination (5 test cases)
- TestMediaItemLibraryRequirement (2 test cases)
- TestUpdateMediaItemISBN (1 test case)
Features:
- Tests use /api/media-items endpoint (not deprecated /api/ebooks)
- Real API calls (not mock handlers)
- Comprehensive ISBN-10/ISBN-13 normalization coverage
- Pagination validation with limit/offset edge cases
- Library requirement validation
This replaces the functionality lost from isbn_and_library_test.go
with modern, working tests using current API endpoints.
Phase 3: Test Suite Cleanup - Replacement Tests
- Deleted isbn_and_library_test.go (507 lines)
- All tests used deprecated /api/ebooks endpoint
- Tests were mock-based, not real API calls
- Functionality will be replaced with modern tests
This is part of legacy code cleanup Phase 3.
Phase 3: Test Suite Cleanup
- Removed TestPaginationAndFiltering function
- Deleted 4 test cases using deprecated /api/ebooks endpoint
- Tests for pagination already exist in library_test.go using /api/media-items
This is part of legacy code cleanup Phase 3.
Phase 3: Test Suite Cleanup
- Removed comment about 'Ebook notes handlers (backward compatibility using views)'
- Removed comment references to non-existent GetEbookNotes and GetEbookHighlights
- Cleaned up misleading legacy documentation
This is part of legacy code cleanup Phase 1.
Phase 1: Documentation Cleanup
- Removed comment about user_ebook_folders table replacement
- Removed comment about library system transition
- Historical migration documentation removed
This is part of legacy code cleanup Phase 1.
Phase 1: Documentation Cleanup
- Removed 'Ebook Compatibility (Backward Compatible)' section
- Removed 'Backward Compatibility Views' from database docs
- Removed backward compatibility bullet point from Database Schema section
- Cleaned up legacy API references from README
This is part of legacy code cleanup Phase 1.
Phase 1: Documentation Cleanup
- Analytics API endpoints (reading stats, device usage, popular books)
- Bulk operations for conflicts, books, and collections
- Book matching and auto-linking endpoints
- Unlinked book management
- OPDS on-the-fly conversion
- Request/response examples for all endpoints
- Authentication requirements and error handling
Sync-Kobo:
- Auto link books endpoint tests
- Bulk link books endpoint tests
- Get unlinked book suggestions endpoint tests
OPDS:
- Download book with on-the-fly KEPUB conversion tests
All tests cover no user, user, and admin contexts
- Display paginated list of unresolved unlinked books
- Show match suggestions with confidence scores
- Bulk linking interface
- Auto-link with configurable threshold
- Device and file metadata display
- Integrate conversion service with OPDS handler
- Convert EPUB to KEPUB format on download request
- Cache converted files to reduce processing time
- Support per-device catalog with format availability
- Maintain backward compatibility with existing downloads
- BulkLinkBooks: manually link multiple unlinked books to media items
- AutoLinkBooks: automatically link books above confidence threshold
- GetUnlinkedBookSuggestions: get match suggestions for specific unlinked book
- Support batch operations with individual result tracking
- Configurable confidence thresholds and limits
- Add reading stats endpoint with daily/monthly history
- Add device usage statistics (sync count, time spent)
- Add popular books view with completion rates
- Server-side rendered analytics page with HTMX
- Date range filtering for reading history
Add analytics queries:
- GetUserReadingHistory: detailed reading history with device info
- GetUserDeviceUsage: device usage statistics (sync count, time spent)
- GetPopularBooks: most read books with completion rates
Add book matching queries:
- GetUnlinkedBookByID: fetch single unlinked book
- DeleteUnlinkedBook: remove resolved unlinked book
- ListUnresolvedUnlinkedBooks: paginated list of unresolved books
- Install kepubify binary in Dockerfile for on-the-fly conversion
- Add conversion service with caching layer (24hr TTL)
- Support KEPUB downloads through OPDS endpoint
- Cache converted files to reduce processing overhead
- Add environment configuration for cache directory and tool path
This plan implements the remaining features from the original implementation plan:
- Phase 1: File Conversion Pipeline (EPUB→KEPUB with dual hash storage)
- Phase 2: Advanced Unlinked Book Resolution (bulk operations)
- Phase 3: Conflict Resolution UI & API
- Phase 4: Analytics & Reporting Dashboard
- Phase 5: Bulk Operations API
- Phase 6: WebSocket Real-time Updates
Each phase is atomic, independently testable, and includes:
- Complete implementation code
- Database queries
- Frontend templates
- Bruno API tests
- Unit tests
The plan is designed to be implemented by any AI with knowledge of
Go, Echo framework, PostgreSQL, and HTMX.
Remove exception for htmx.min.js so all compiled JavaScript in
web/static/ is ignored and generated during Docker build.
The Dockerfile already handles downloading HTMX via:
- npm postinstall script
- Downloads from unpkg.com during container build
This keeps the repository clean and lets the container build
process generate all static assets consistently.
john-okeefe