Study/README.md
Elijah 031f7bec31
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
Second revision: MCP servers, shared-link AI, flashcard modes, document previews
Generation
- Every quiz is NCLEX style; "Practice exam" writes 50 questions.
- Calculation questions only when the material involves calculations (max 5 per exam).
- Broad topics: the class's topics are listed in the prompt, a quick grouping call maps
  narrow labels onto broad ones, and leftover variants are merged.
- Exact select-all count per batch; option order shuffled.
- Python check: at most 3 runs, fixed problems count as passed, cosmetic remarks ignored.

Assistant
- Text, tool steps and cards appear in the order they happen, with paragraph breaks
  between steps.
- Optional thinking box: fixed height, follows the newest text, can be scrolled back.
- "+" opens a material picker listing recent items; items can be dragged in from class
  pages; shorter placeholder.

MCP servers
- Streamable HTTP client; encrypted headers.
- Per-server instructions and switches for chat, Explain, generation and the quiz check.
- Settings UI.

Share links
- Optional "Explain this" and "Ask about this material" per link, off by default.
- Items are loaded on the server and checked against the share; no tools; rate-limited.
- Migration 4 stores the switches.

Study and documents
- Standard flashcard mode (optionally repeat missed cards until known) next to spaced
  repetition.
- Streak visuals restyled in the app palette.
- Side by side / Original document views, with sandboxed previews of Word and PowerPoint
  files.

Other
- Built-in embedding model baked into the image; sharp stubbed if it cannot load; real
  load error shown in Settings.
- Python runner blocks network and process modules in JavaScript too.
- "View questions and answers" removed from the quiz start screen.
- Docs updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 15:48:54 -07:00

95 lines
4.8 KiB
Markdown

# Study Desk V2
A personal study platform for nursing school: classes and folders, quizzes, FSRS flashcards,
notes, private documents, and AI-assisted content creation. One administrator; friends study
through revocable public links without accounts.
## Run locally
Requires Node.js 24 or newer and npm. The development VM currently uses Node 26.
```powershell
npm.cmd ci
npm.cmd run dev
```
Open the Vite address printed in the terminal (normally http://localhost:5173).
The API listens on port 3726. For the production build locally:
```powershell
npm.cmd run build
npm.cmd start
```
Open http://localhost:3726. On a fresh install, enter the setup code from the server log or
`data/setup-code.txt`, then choose your administrator password. Alternatively set
`ADMIN_PASSWORD` for first startup. An optional `.env` file is loaded by the server; see
[.env.example](.env.example). Existing environment variables take precedence.
**This checkout already has an ignored `.env` pointing at `.data/` from development.**
Do not delete it or run reset/seed commands against content you want to keep. The demo seeder
is an opt-in development tool, never part of startup.
## What is implemented
- Classes, folders, search, edit/duplicate/move/delete actions; Markdown and embedded images.
- Multiple-choice, select-all and numeric (type-the-answer calculation) questions; a start
screen that hides answers, practice feedback, optional exam time limits, shuffle, partial
credit, saved sessions, missed-question review, 7-point letter grades and history.
- Flashcard editing, browse/self-assessment sessions, FSRS scheduling, persistent reviews,
undo, keyboard shortcuts and streak effects.
- Public quiz/deck/class/folder/note/document links. Collection (class and folder) shares
include current and future quizzes, decks, notes and processed documents. Each link can
allow "Explain this" and a chat about the shared material, separately (off by default).
- Flashcards in Standard mode (know it / still learning, optionally repeating missed cards
until known) or spaced repetition.
- JSON import previews, validation, templates, content exports and a V1 SQLite import path.
- PDF/DOCX/PPTX/TXT/Markdown/image uploads; text extraction, OCR via a configured vision model,
chunking and SQLite FTS retrieval with source references. The original is shown next to the
extracted text (Word and PowerPoint as a generated preview).
- OpenAI, Anthropic, Gemini, DeepSeek, OpenAI-compatible and Ollama provider connections,
manual/discovered models, task routing with reasoning effort from Off to Max, encrypted keys
and usage estimates that price cached input separately.
- Semantic search with cloud embeddings or a built-in model that runs on the server.
- AI generation with editable drafts and editable instructions/presets; generation and
assistant answers keep running on the server when you leave the page. The assistant
searches materials, reads notes, creates drafts, finds weak topics, proposes confirmed
content changes, accepts tagged or dragged-in materials, can switch models per chat and can
show its reasoning. It runs Python in a sandbox, and generated quizzes are checked with it.
- MCP servers (Streamable HTTP) as extra assistant tools, each with your own instructions and
switches for chat, explanations, generation and the quiz check.
- Responsive light/dark interface and an installable app shell. Offline studying is limited:
private data is not cached; most operations need a server connection.
## Deploy, back up, migrate
See [deployment and restore](docs/DEPLOYMENT.md), [V1 migration](docs/MIGRATION.md), and
[AI providers and account integration](docs/AI.md).
The image runs a single Node process with SQLite and local file storage. No database or queue
container is required. The container runs as UID/GID 1000 and persists everything under `/data`.
```sh
docker compose up -d --build
```
Default V2 host port: **3727**, deliberately separate from the old application. Use a separate
data folder. Docker Desktop image build and disposable-container runtime checks now pass;
Unraid-specific permissions and reverse-proxy checks remain. No production deployment has
been performed.
## Verification and resuming work
```powershell
npm.cmd run check
```
Tests create isolated temporary databases. AI integration tests use a local mock server and
need loopback networking. They do not spend provider credits. Real provider credentials,
account-specific model access, Linux container behavior and Unraid proxy configuration must
be checked in their target environments.
[PROGRESS.md](PROGRESS.md) records completed work, remaining verification, decisions and the
resume procedure. V1 remains on `main` and in Git history; V2 work is on the `v2` branch.
Pushing `v2` to Forgejo runs CI and publishes the `study:v2` image (never `:latest`); see
[deployment](docs/DEPLOYMENT.md). Nothing deploys automatically.