5.6 KiB
Study Desk V2 — progress and resume notes
Updated 2026-11-11. Branch: v2. Original V1: main, preserved at 7bd0a9a.
Work remains local; no push, repository creation or production deployment has been performed.
Product and architecture
This is a rebuilt app using React + Vite + TypeScript, Hono/Node HTTP server, built-in
node:sqlite, SQLite FTS5, local document storage and a persistent document queue. One process,
one data volume, one administrator. Anonymous visitors get public read-only shares and
browser-local study progress. Administrator progress stays server-side.
The previous agent implemented the core product and committed it through c549c34:
classes/folders, CRUD/duplicate/move/search, quiz sessions/results/history, FSRS flashcards,
imports/exports/templates, documents/extraction/retrieval/OCR, provider adapters, editable
AI drafts, tool-based assistant actions, sharing, analytics and the responsive themed UI.
User feedback fixes are already included: larger clickable flashcards, arrow keys, streak
effects, persistent review sidebar, live quiz score, shared quiz timers, SATA credit details,
type-grouped materials, copyable import instructions and assistant library links.
Current continuation
- Confirmed original 162 tests pass; sandbox networking initially blocked the mock provider.
- Added encryption-key corruption/missing-key refusal, static-path boundary validation, private embedded-media authorization and share-revocation checks.
- Full backups include the generated encryption key and fail on unreadable files.
- Added backup restore, media authorization, key durability, V1 import and failed-migration rollback tests. The new V1 test checks source bytes are unchanged and state is preserved.
- Added Dockerfile, Compose, .dockerignore, README and deployment/migration/AI documentation.
- Updated obsolete ChatGPT subscription wording after checking official documentation: account integration exists for eligible clients, but hosted app approval for this private Unraid web deployment has not been established. API integration remains the working path.
- Terra completed isolated UI/workflow and visual QA; see results below.
- Guarded quiz exit/submission when the latest save failed, and prevented repeated automatic timer submissions after a failed request.
Verification status
Baseline: 162 tests passed, TypeScript passed and production web/server builds passed.
Added five regression tests. Full npm run check passes: 167 tests, TypeScript and both
production builds. Tests were run with loopback access for the mock provider.
The earlier agent manually exercised quiz completion/results, flashcards, streak effects, mock AI generation through the assistant, editable drafts, and a 375px home page without horizontal overflow. Treat these as historical evidence; record Terra's fresh results below.
Not verified: actual Docker image build/runtime, Unraid filesystem permissions and proxy, paid provider inference, real ChatGPT OAuth/eligibility. Docker is not installed here. Do not claim these have been tested. The installable app caches its shell, not private study data; full offline administrator study is not implemented.
Remaining work
- Finish the brief post-fix Terra contrast recheck and public visitor UI check.
- Record its results, review the diff and commit locally.
- On Unraid later: execute the deployment/restore checklist in docs/DEPLOYMENT.md.
- With owner-supplied provider connections: verify live discovery, streamed chat, generation, OCR and task routing. No real-provider calls should be inferred from mock test results.
- Future optional work: approved ChatGPT account OAuth, more robust offline studying and semantic embeddings (current retrieval is lexical FTS5).
Resume safely
git status --short, read this file and recent commits. Do not overwrite user changes.- The ignored
.envcurrently selects.data/, containing dev/demo content that the user has tried. Never print its secrets or reset/seed it casually. Use a new.test-data/...directory and a separate port for destructive QA. npm.cmd run check(tests require localhost networking for their mock AI server).npm.cmd run devfor Vite + API, ornpm.cmd run buildthennpm.cmd startfor the built app. See README and .env.example. All automated test databases are disposable copies.- Keep regular local commits on
v2. Do not push until the owner explicitly changes the original local-only instruction. Publishing later can usegit push -u origin v2after reviewing the diff and confirming credentials; no force push is needed.
Fresh UI QA findings
Terra tested through Edge in an isolated volume on port 3731. Observed successful login, class creation, quiz/question editing, practice start, save/exit, resume, answer check and 100% results; deck/card creation, browse flip, FSRS review, pasted question import; desktop and emulated 400×933 mobile layouts in both themes. No obvious clipping or overlap observed on those screens. The test server was stopped and the temporary password removed.
Visual finding: secondary labels appeared faint, particularly in dark mode. Adjusted the
shared ink-3 colors. Computed WCAG contrast against paper/surface/sunken backgrounds:
light now 5.15 / 5.38 / 4.76 (previously 3.48 / 3.63 / 3.21); dark now
7.42 / 6.86 / 7.71. These ratios cover these token pairs, not a full accessibility audit.
Screenshots remain ignored under .test-data/ui-terra/: desktop-dark-quiz.png,
desktop-light-quiz.png, mobile-dark-quiz.png, mobile-light-quiz.png and mobile-light-session.png.
Post-fix visual and anonymous-share recheck pending.