initial 2

apps/web/docs/REFACTOR-LOG.md

@@ -0,0 +1,74 @@
+# Refactor Log
+
+Internal refactor of AdventureOS. Behaviour, API contracts, and schema preserved unless explicitly noted.
+
+## Phase 1: Safety baseline
+
+- Removed debug telemetry from `apps/web/src/app/api/library/books/route.ts`
+- Extracted pure adventure helpers: `derive-state.ts`, `template-matching.ts`, `checklist-value.ts`
+- Added unit tests for `@adventureos/shared` (xp, levels, scores, chapters)
+- Added characterization tests for deriveState, template matching, undo Calibre mismatch
+- Replaced misnamed `feature-repair.test.ts` with real tests
+
+### Manual smoke checklist
+
+- [ ] Login / logout
+- [ ] Command Centre: adventure items, todos, rest day, customize
+- [ ] Settings: theme, AI config, templates, action history undo
+- [ ] Library: manual books and Calibre (if configured)
+- [ ] Cartographer: generate, activate, complete, dismiss
+- [ ] Teacher: generate, complete, deep links
+- [ ] Undo toast and settings undo
+
+### Commands run each phase
+
+```bash
+npm run test
+npm run lint
+npm run build
+npm run db:migrate   # when DB available
+```
+
+## Phase 2: Configuration and constants
+
+- Centralised env reads in `lib/config/`
+- Typed constants for settings keys, action types, theme IDs
+
+## Phase 3: API and data access
+
+- Zod input validation on teacher, templates, settings routes
+- Repository layer for settings, teacher, adventure templates
+- Typed errors in `lib/errors/`; `handleApi` uses `mapErrorToResponse`
+- Teacher route uses `createTeacherLesson` service
+
+## Phase 4: Domain/service cleanup
+
+- Split `adventure.ts` into `lib/services/adventure/{materialization,daily,scoring,templates}.ts`
+- Unified Calibre reading log via `lib/services/reading/log-pages.ts`
+
+## Phase 5: Frontend cleanup
+
+- Client API: `features/adventure/api.ts`, `features/undo/api.ts`, `lib/api-client.ts`
+- Hooks: `useAdventureMutations`, `useUndoMutation`, `useActionToastHandlers`
+- Split `todays-adventure.tsx`; extracted `adventure-item-row`, `checklist-item`
+- Consolidated AI prompt editors into `AiPromptEditor`
+- Shared UI: `RetroWindow`, `TabToggle`, `LoadingState`, `ErrorState`
+- Undo toast uses query invalidation (no full page reload)
+
+## Phase 6: Type safety
+
+- JSONB interfaces in `lib/types/jsonb.ts`
+- Teacher types in `@adventureos/shared`
+- Removed unused `@radix-ui/*` dependencies
+
+## Phase 7: Tests and CI
+
+- Validation/error unit tests
+- `@adventureos/shared` test script and vitest config
+- Root `npm run test` runs web + shared
+- GitHub Actions CI workflow
+
+## Phase 8: Documentation
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — layers and service boundaries
+- [KNOWN-ISSUES.md](./KNOWN-ISSUES.md) — documented gaps