Study/PROGRESS.md
Elijah 85d5c9186d
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m0s
Fifth revision: share-link AI safety, sturdier generation, cleaner UI
- Malformed model JSON is sent back for repair, then retried; a failed job
  starts over once before it fails. Visitors can dismiss failed sets.
- Generated sets get a short distinct name and description; flashcards are
  atomic and have no hints; standard study shows known/learning counts.
- Share links: "In progress" list, finished sets join the normal lists with a
  "New" tag, plain progress steps, newest exam first.
- Share-link AI expires after a week, can be limited to the US or Arizona
  (DB-IP Lite or Cloudflare headers) and is locked by abuse protection
  (migration 8).
- The assistant never answers from general knowledge; MCP and web search
  tools load without a manual test.
- Plain-text copy, no question count in exam mode, filler text removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 09:17:50 -07:00

251 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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).
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: **274 tests** (fifth revision, 2026-11-16; 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.