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.
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
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
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.
BREAKING CHANGE: Documentation URLs have changed
New structure:
- user/ - End-user documentation (device setup, sync guides, frontend)
- developer/ - Developer documentation (API reference, protocols, specs)
- operations/ - Operations documentation (deployment, troubleshooting)
- contributing/ - Contribution guides
Changes:
- Created portal INDEX.md files for each audience section
- Moved device guides to user/devices/ (kobo-setup.md, koreader-setup.md)
- Moved API docs to developer/ (api-reference.md, collections-api.md)
- Moved sync guide to user/sync-guide.md
- Moved troubleshooting to operations/troubleshooting.md
- Moved all split API docs to developer/api/
- Renamed protocol files (kobo-protocol.md, koreader-protocol.md)
- Added placeholder user guides (frontend, user-areas, settings, admin)
- Updated all internal links to new paths
- Updated Go code (http_handler.go, navigation.go) for new paths
- Updated main INDEX.md for audience-based navigation
Benefits:
- Clear separation of user and developer documentation
- Scalable structure for future user guide expansion
- Better organization and discoverability
- Audience-specific landing pages
Related to DOCS_IMPLEMENTATION_PLAN.md Phase 2 completion
john-okeefe