All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 29s
- Settings -> AI: Planning, Writing, Python check and Second review each get their own model, reasoning effort, temperature and output limit, shown under Content generation. Unset choices follow Content generation, then the default model. - Shared quizzes say what Practice and Exam mean under the mode toggle. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
265 lines
18 KiB
Markdown
265 lines
18 KiB
Markdown
# Study Desk V2 — progress and resume notes
|
||
|
||
Updated 2026-11-12. Branch: **v2**. Original V1: **main**, preserved at `7bd0a9a`.
|
||
The owner authorized publishing progress and `v2` now tracks Forgejo `origin/v2`.
|
||
No 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, static-path traversal, 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.
|
||
- Preserved the V1 card elapsed-days scheduling field during import.
|
||
|
||
## 2026-11-12 additions
|
||
|
||
- `.forgejo/workflows/build-v2.yml`: pushes to `v2` run typecheck + tests inside the Node 24
|
||
image (new Dockerfile `test` stage), build and smoke-test the production image, then publish
|
||
`study:v2` and `study:v2-<sha>`. Never `:latest`. Verified locally with Docker Desktop; the
|
||
workflow itself has not run on the Forgejo runner yet (nothing pushed).
|
||
- Drag-to-reorder (`web/src/ui/Sortable.tsx`, pointer events so touch works, keyboard with
|
||
arrows/Home/End and live announcements) for class materials, folders, questions and cards.
|
||
New endpoint `POST /api/classes/:id/items/reorder`.
|
||
- Timed exams use a wall-clock `deadlineAt` stored in attempt settings. The server refuses late
|
||
answers (409 `time_up`), submits overdue exams lazily and before every authenticated GET,
|
||
and caps time used at the limit. Shared exams use a local wall-clock deadline too.
|
||
- Shared quiz sessions freeze their questions (with option order) in browser storage, with a
|
||
fingerprint to tell the visitor when the owner has since edited the quiz.
|
||
- Scanned PDFs are read in 8-page batches split with pdf-lib, cached per batch, with real page
|
||
numbers. OpenAI-compatible adapter now sends PDFs as Chat Completions `file` parts when the
|
||
model is marked as PDF-capable.
|
||
- Semantic search: migration `2_embeddings` (`chunk_vectors`), embedding support in the
|
||
OpenAI/Gemini/Ollama/compatible adapters, `server/services/semantic.ts` (background indexing,
|
||
in-memory cosine search, reciprocal-rank fusion with FTS), Settings → AI section.
|
||
- Browser QA on an isolated `.test-data/qa` instance (port 3742, `study-qa` launch config):
|
||
drag and keyboard reorder persisted; 375px class page has no overflow; semantic search
|
||
enabled from Settings and indexed; a 1-minute exam counted down on the wall clock and
|
||
auto-submitted at 60 s; a shared session kept original questions after the owner edited them.
|
||
|
||
## 2026-11-15: first revision (owner's 21-item list)
|
||
|
||
Implemented and verified on an isolated instance (`.test-data/rev1`, port 3743):
|
||
DeepSeek provider (`server/ai/providers/deepseek.ts`); 7 reasoning-effort levels mapped per
|
||
adapter; the "does not support tool calling" errors were DeepSeek rejecting forced tool choice
|
||
in thinking mode: compatible servers now get the call requested in the prompt, and only a
|
||
genuine "no tools" 400 reports unsupported. Cached-input prices (migration 3) and cache-write
|
||
/off-peak aware costs. Built-in embeddings (`server/ai/localEmbed.ts`, bge-small, default when
|
||
nothing is chosen). Assistant turns run server-side independent of the browser (re-attach via
|
||
`GET /api/ai/chat/:id/stream`, stop via `POST /api/ai/chat/:id/stop`); drafts tray in the
|
||
sidebar/Today. Quiz start screen, navigator ring/legend fix, timer only for timed exams,
|
||
7-point letter grades, numeric questions (migration 3 rebuilds `questions` for the new type;
|
||
answers are compared numerically, units ignored, optional ± tolerance). Dialog footer padding
|
||
(`safe-pb-3`), keyboard hints removed, small assistant button, full-width assistant page, model
|
||
switcher and @-tagging. Editable generator instructions and built-in presets (builtin = 2 marks
|
||
an edited built-in), separate chatbot import instructions. Copy buttons work over plain HTTP
|
||
inside dialogs. Class/folder shares include processed documents.
|
||
|
||
Live DeepSeek (`deepseek-flash` only) checks passed: discovery, quiz generation at default and
|
||
Max effort (numeric items produced, answer keys correct with thinking on), multi-step tool
|
||
turns, follow-up turns, tagged quiz to flashcards, an answer finishing after disconnect; zero
|
||
errors in Usage. Docker image builds; ONNX Runtime and the embedding model run in the container.
|
||
The image grew to about 1.3 GB because of ONNX Runtime.
|
||
|
||
## 2026-11-15: second revision (owner's 19-item list)
|
||
|
||
Quiz generation: all quizzes NCLEX; "Practice exam" = 50 questions; calculation questions only
|
||
when the source mentions calculations (max 5 in an exam); broad topics (prompted, plus
|
||
`consolidateTopics` merging narrower labels); option order shuffled. The Python check uses at
|
||
most 3 runs and ignores cosmetic remarks. Assistant: text, tool steps and cards stream in the
|
||
order they happen (`MessagePart`), paragraphs are separated between steps, optional "Show
|
||
thinking" box (persisted, fixed height, follows the newest text), "+" opens a material picker
|
||
(no more flashing "@"), library items can be dragged into the panel, shorter placeholder.
|
||
"View questions and answers" removed from the quiz start screen. Built-in embedding model baked
|
||
into the image (`scripts/fetch-embedding-model.mjs`, `LOCAL_MODELS_DIR`), sharp stubbed when its
|
||
native binary will not load, and the real load error shown in Settings. Python runner also blocks
|
||
network and process modules in JavaScript (Node 24's permission model does not block network).
|
||
|
||
New: MCP servers with per-server instructions and per-area switches (`server/ai/mcp.ts`,
|
||
`runChatWithMcp` in `service.ts`); per-share AI switches (migration 4, `shares.ai`;
|
||
`POST /api/public/:token/explain|chat`, limited per device via a signed visitor cookie plus a
|
||
per-link cap; MCP servers join only with their "Share links" switch on); flashcard Standard mode with
|
||
"repeat missed cards until known" next to Spaced repetition on the deck page; streak visuals
|
||
restyled in the app palette (marker highlighter, accent bar, mono numerals); document Side by
|
||
side / Original view with generated previews for Word and PowerPoint. Item 13 (pictures in
|
||
PowerPoint files) was verified only: they are not read; see docs/AI.md.
|
||
|
||
Tests: `tests/revision2.test.ts` (mock MCP server over Streamable HTTP and SSE, area switches,
|
||
instructions in prompts, exam length, calculation allowance, topic merging, message part order,
|
||
previews, share-link AI scope and rate limits).
|
||
|
||
## 2026-11-15: third revision (owner's 13-item list, plus exams and clarifying questions)
|
||
|
||
Built-in Parallel web search (keyless, optional sign-in) with its own settings page; OAuth for
|
||
every MCP server (`server/ai/mcpAuth.ts`); friendly tool steps (`web/src/features/ToolSteps.tsx`,
|
||
`server/ai/activity.ts`) with ids stripped from results; thinking box 50% taller; per-chat
|
||
tool switches; share-link assistant button matches the owner's and hides during a quiz or
|
||
deck; share-link documents readable in the browser (original or text, page by page); live
|
||
updates over SSE (`GET /api/events`, drafts and library); quiz results show a % ring
|
||
coloured by band (rainbow at 100, green 93–99, blue 85–92, yellow 77–84, red below 77);
|
||
Explain opens beside the quiz on wide screens and reads the cited source pages;
|
||
OpenUI blocks in all chats; exams within classes (migration 5 adds `classes.group_label` and
|
||
`conversations.settings`); assistant clarifying questions (`ask_user`,
|
||
`web/src/features/AskCard.tsx`).
|
||
|
||
Item 13 (beta container losing its data on update): the code keeps the database and secret key
|
||
in `/data`, and compose.yaml mounts `${STUDY_DATA_DIR:-./data-v2}:/data`. Data is lost only when
|
||
the container runs without that mount (the image's `VOLUME` then gives each new container a new
|
||
anonymous volume). Map `/data` to a host path in the Unraid template.
|
||
|
||
Tests: `tests/revision3.test.ts` (web search, OAuth with a mock authorization server, live
|
||
events, cited pages, shared document text, genui prompt, clarifying questions, exam-scoped
|
||
generation).
|
||
|
||
## 2026-11-15: fourth revision (owner's 12-item list)
|
||
|
||
Interactive blocks encouraged by default (and never practice questions in Explain); Generate
|
||
dialog's practice set / exam switch removed (the preset covers it); Explain beside the question
|
||
on screens from 900px wide, moving the question left while open; breathing indicator and live
|
||
stages on the assistant's tool steps, past-tense lines when done; no icon on Generate; the
|
||
assistant asks before searching the web when the class materials do not cover a question;
|
||
clarifying questions offer the class's exams and never ask about format (always NCLEX);
|
||
Python check notes are green when every check passed, applied fixes neutral; share pages
|
||
grouped by exam, then Quizzes, Flashcards, Notes, Class Materials (empty groups hidden, same
|
||
order on the class page); "Documents" renamed "Class Materials"; OpenRouter provider
|
||
(`server/ai/providers/openrouter.ts`) replacing the Ollama type (migration 6 turns Ollama
|
||
connections into OpenAI-compatible ones at `/v1`).
|
||
|
||
Tests: `tests/revision4.test.ts`; OpenRouter cases in `server/ai/providers/providers.test.ts`.
|
||
|
||
Follow-up the same day: visitors of class and exam links can generate quizzes (default and
|
||
maximum 50 questions, 25% select-all, optional 5 med math questions) and flashcards from chosen
|
||
class materials (flashcards up to 75), 4 quizzes and 2 flashcard sets per link per day with a
|
||
reset in the share dialog (`server/routes/shares.ts`, `web/src/features/SharedGenerate.tsx`,
|
||
migration 7). Sets show in Drafts while written, then save into the class or exam
|
||
automatically, and stay when the link is deleted. The
|
||
owner's Generate dialog gained "Include med math" with a count (default 5).
|
||
|
||
## 2026-11-16: fifth revision (owner's 18-item list)
|
||
|
||
Explanatory filler removed across the UI (share page, Generate dialogs, start screens, settings,
|
||
flashcards); share-link "In progress" list for sets being written, finished sets join the normal
|
||
lists with a "New" tag for two hours; visitors see "Verifying questions"; exam mode has no
|
||
question-count slider (an exam is always the whole quiz); newest exam first on share pages;
|
||
malformed JSON repaired by the model, retried, then the whole job restarted once; failed sets
|
||
dismissable on the link only; plain-text copy everywhere; generated sets get their own short
|
||
name and description; atomic flashcards without hints; a known / still learning counter in
|
||
standard flashcard study; the assistant never answers from general knowledge (search or say it
|
||
has no information); MCP and web search tools load automatically; share-link AI expires after a
|
||
week, can be limited to the US or Arizona (`server/services/geo.ts`, DB-IP Lite) and is locked
|
||
by abuse protection (migration 8).
|
||
|
||
Follow-up the same day: the quiz check no longer hands over a quiz with known problems. It can
|
||
rewrite a whole question, removed questions are replaced, a second independent review reads the
|
||
whole quiz for badly written items (a writer changing its mind mid-stem), and the quiz is
|
||
checked again until it passes (at most three rounds).
|
||
|
||
Speed (timed live on a 50-question quiz): output limits now leave room for reasoning (calls at
|
||
"max" were being cut off at 16k tokens), questions are planned before writing so batches can run
|
||
four at a time without overlapping, replacements are planned and parallel too, and the two
|
||
reviews run side by side. 50 questions: 7 min 21 s, 0 duplicates, all checks passed.
|
||
|
||
Settings → AI now has separate Planning, Writing, Python check and Second review rows under
|
||
Content generation (each inherits until set), and shared quizzes say what Practice and Exam
|
||
mean under the mode toggle.
|
||
|
||
Tests: `tests/revision5.test.ts`. Live check on the rev1 copy with DeepSeek flash: a visitor's
|
||
10-card set was written, named ("Heparin, Furosemide, and Dosage Calculations"), saved and
|
||
listed once with the New tag; cards were single facts with no hints. The rev1 copy's 401 was its
|
||
stored DeepSeek connection still holding the old key; it was updated from `.env`.
|
||
|
||
## Verification status
|
||
|
||
Baseline: 162 tests passed, TypeScript passed and production web/server builds passed.
|
||
Added six regression tests. Full `npm run check` passes: **281 tests** (generation steps, 2026-11-16; 280 after the check loop and second review; 274 after the fifth revision; 261 after share-link generation, 2026-11-15; 257 after the fourth revision; 247 after the third, 208 after the second, 181 on 2026-11-12), TypeScript
|
||
and both production builds. The Docker `test` stage runs the same 181 tests on Node 24. 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.
|
||
|
||
Docker Desktop is now installed. Image build and a disposable non-root container passed
|
||
login, document/card persistence across restart, full-backup ZIP, anonymous sharing and
|
||
private API denial. Still unverified: Unraid filesystem permissions/proxy, paid-provider
|
||
inference and real ChatGPT OAuth/eligibility. The installable app caches its shell, not private study data;
|
||
full offline administrator study is not implemented.
|
||
|
||
## Remaining work
|
||
|
||
1. On Unraid later: execute the deployment/restore checklist in docs/DEPLOYMENT.md.
|
||
2. 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.
|
||
3. Future optional work: approved ChatGPT account OAuth, more robust offline studying and
|
||
(semantic embeddings were added on 2026-11-12, the built-in model on 2026-11-15).
|
||
|
||
## Resume safely
|
||
|
||
1. `git status --short`, read this file and recent commits. Do not overwrite user changes.
|
||
2. The ignored `.env` currently 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.
|
||
3. `npm.cmd run check` (tests require localhost networking for their mock AI server).
|
||
4. `npm.cmd run dev` for Vite + API, or `npm.cmd run build` then `npm.cmd start` for the built
|
||
app. See README and .env.example. All automated test databases are disposable copies.
|
||
5. Keep focused commits on `v2`. The owner has now authorized pushing progress to this branch;
|
||
Git Credential Manager works. Never force push or publish/deploy to production implicitly.
|
||
|
||
## V1 comparison and follow-up usability work
|
||
|
||
See `docs/V2-COMPARISON.md` for the requirement matrix, V1 differences and remaining priorities.
|
||
Fixed the flashcard entrance/exit CSS conflict; restored touch grading and shuffle-remaining;
|
||
reset review queues on scope changes; serialized note autosaves, protected navigation with
|
||
unsaved edits and added an explicit retry action. Verified a note survives immediate
|
||
navigation and reload, and shuffling keeps browse progress at 2/4 rather than restarting.
|
||
|
||
The owner's rationale check passed using a synthetic three-question quiz with per-option
|
||
explanations: correct, incorrect and partial SATA feedback all show explanations inline under
|
||
their options. Results group explanations with each question. Screenshot is ignored at
|
||
`.test-data/rationale-check/correct-inline.png`. The temporary test server is stopped after QA.
|
||
|
||
## 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 Terra recheck: desktop light/dark screenshots show improved secondary-text legibility
|
||
(`postfix-dark-desktop.png`, `postfix-light-desktop.png`). An Edge InPrivate visitor opened
|
||
the isolated shared quiz without login, completed practice, saw its rationale and reached
|
||
100% results. Shared-deck UI, long-label layout stress tests and post-fix mobile contrast were
|
||
not revisited in this follow-up. Public deck data isolation/revocation is covered by API tests.
|
||
No known functional failures were found in the UI paths exercised. This is sampled QA, not
|
||
an exhaustive audit of every layout and browser. Terra's isolated server is stopped.
|