initial 2

apps/web/docs/KNOWN-ISSUES.md

@@ -0,0 +1,41 @@
+# Known Issues
+
+Issues discovered during refactor audit. Not fixed unless explicitly approved (behaviour preservation).
+
+## Calibre reading undo is broken
+
+Both manual (`reading.ts`) and Calibre (`calibre-reading.ts`) use `actionType: "reading.log_pages"`.
+
+- Manual: `beforeState: { book: { currentPage, status, finishedAt } }`, `entityType: "book"`
+- Calibre: `beforeState: { currentPage, status }`, `entityType: "reading_progress"`
+
+`undo.ts` case `"reading.log_pages"` only restores the manual `books` table. Undoing Calibre page logs will fail or corrupt state.
+
+## Cron middleware requires session
+
+`middleware.ts` does not exempt `/api/cron`. External cron with only `x-cron-secret` (per README) receives 401 before the route handler runs.
+
+## Partial undo coverage
+
+- `applyTemplateToDate` records no action event
+- Template item create/update not recorded (only delete)
+
+**Fixed:** Reflection saves now record `reflection.save` action events for undo.
+
+## HTTP status codes
+
+`handleApi` maps thrown `"Item not found"` to 500, not 404. Normalising would change API contract.
+
+## Dashboard may ignore Calibre progress
+
+Stats and dashboard reading metrics query manual `books` / `reading_logs`; Calibre `reading_progress` may not feed scores.
+
+## Dead / unused code
+
+- `packages/shared/src/titles.ts` — exported, never imported
+- `action_events.inversePatch` — written, never read in undo
+- `getCalibreBook()` in calibre.ts — no-op implementation
+
+## Undo UX inconsistency
+
+Toast undo (`overlays.tsx`) reloads the page; settings undo invalidates React Query cache.