@priyadarship4/coursy 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+# Coursy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local-first AI study companion for downloaded video and text courses. Point it at a folder of
+course videos; it plays them like a curriculum, tracks progress, and builds an AI layer on top:
+per-lesson summaries, scene navigation, practice questions, voice mock interviews, and a
+personalized study plan.
+
+## Requirements
+
+- Node.js **22.13+**
+- `ffmpeg` + `ffprobe` on PATH — needed for AI enrichment only; playback works without them:
+  - macOS: `brew install ffmpeg`
+  - Windows: `winget install Gyan.FFmpeg` (or `choco install ffmpeg`)
+  - Linux: `sudo apt install ffmpeg` (Fedora: `sudo dnf install ffmpeg`, Arch: `sudo pacman -S ffmpeg`)
+  - Custom installs: `COURSY_FFMPEG_PATH` / `COURSY_FFPROBE_PATH` (file or directory)
+- Optional: an OpenAI-compatible LLM key (DeepSeek, OpenCode Go, OpenAI, OpenRouter, Ollama, …)
+- Optional transcription: subtitles (`.srt`/`.vtt`) next to videos, a Whisper-compatible API key, or
+  FluidAudio on macOS for fully local transcription
+
+Missing dependencies never break playback: Coursy shows a warning with the exact fix in
+`coursy doctor`, `coursy status`, the web UI, and disables enrichment actions with the
+reason.
+
+## Data directory
+
+Everything lives in one folder — `~/.coursy` on every OS (override with
+`COURSY_DATA_DIR` or `--data-dir`):
+
+| OS | Path |
+|---|---|
+| macOS | `/Users/<user>/.coursy` |
+| Linux | `/home/<user>/.coursy` |
+| Windows | `C:\Users\<user>\.coursy` (cmd/PowerShell: `%USERPROFILE%\.coursy`) |
+
+It contains `coursy.db`, `media/`, `artifacts/`, `thumbs/`, `coursy.log` and
+`server.json`. Course folders are never written to.
+
+Upgrading from Opencourser: the first run after the rename copies `~/.opencourser` into
+`~/.coursy` automatically (database, media, artifacts, thumbnails). Legacy `OPENCOURSER_*`
+environment variables are still honored, and the `opencourser` command keeps working as an alias
+for `coursy`.
+
+## Quick start
+
+```bash
+npx @priyadarship4/coursy                  # start the server and open the UI (foreground)
+npx @priyadarship4/coursy start --d        # start in the background (daemon)
+npx @priyadarship4/coursy play ~/courses   # add/scan a course folder and open it
+npx @priyadarship4/coursy status           # server, queue, storage and setup status
+npx @priyadarship4/coursy stats            # learning, ai and server stats
+npx @priyadarship4/coursy logs -f          # tail the log (JSON lines on disk)
+npx @priyadarship4/coursy doctor           # check ffmpeg, transcription and LLM setup
+```
+
+Keep a course folder anywhere on disk — Coursy never writes to it. All state lives in
+`~/.coursy` (override with `COURSY_DATA_DIR` or `--data-dir`).
+
+The server runs on **`:4257`** by default (`http://127.0.0.1:4257`). If that port is taken by
+another app, the CLI picks the next free one and tells you (`port 4257 is in use — using 4258`);
+passing `--port` explicitly is strict and fails instead of shifting. The Vite dev client proxies
+to `COURSY_PORT` (default `4257`).
+
+## CLI reference
+
+| Command | What it does |
+|---|---|
+| `start` | Foreground server; `--detach` / `-d` / `--d` runs it in the background |
+| `stop` / `restart` | Manage the background server (pid file: `~/.coursy/server.json`) |
+| `status` | Version, uptime, memory, storage, queue, readiness, recent failures |
+| `stats [learning\|ai\|server]` | Sections: watch time/streaks/practice, LLM + transcription usage, disk/queue health |
+| `logs` | Tail logs; `-f` follow, `-n` lines, `--date`, `--level`, `--grep`, `--path`, `--prune`, `--json` |
+| `config list\|get\|set\|unset` | Read/write settings (secrets masked); same whitelist as the Settings UI |
+| `courses` | Course list with progress, enrichment and practice counts |
+| `revisions [days]` | Due and upcoming spaced-repetition reviews (default 7 days) |
+| `play <path>` | Scan a folder and open the course |
+| `enrich <path\|id>` | Run enrichment for a whole course (`-f` to watch progress) |
+| `remove <id\|slug>` | Delete a course with its AI artifacts, media cache and thumbnails |
+| `export <id\|slug>` | Write summaries, rollups, master notes and the plan as markdown (`--out <dir>`) |
+| `open` / `doctor` / `version` / `help` | Open the UI, environment checks, help |
+
+Global flags: `--data-dir`, `--port`, `--host`, `--json`, `--quiet`, `--no-color`.
+Long options accept unambiguous prefixes (`--det` → `--detach`); command-specific flags win
+(`coursy start --d` → detach, `coursy logs --d` → date, `coursy stats --d` → days).
+
+## Logging
+
+Server logs are JSON lines in `~/.coursy/coursy.log` (requests, enrichment pipeline,
+LLM retries, slow SQLite queries, errors). Daily archives roll to `coursy-YYYY-MM-DD.log`;
+files older than 3 days are gzipped and archives older than 30 days are deleted
+(`COURSY_LOG_RETENTION_DAYS`, `COURSY_LOG_KEEP_DAYS`). Detached servers also pipe
+stdout to `~/.coursy/coursy.out.log`.
+
+## AI setup
+
+Open **Settings → AI enrichment**:
+
+- **LLM**: base URL + model + API key (stored locally in SQLite, never sent anywhere except the
+  provider you configure). Use *Test* to verify. OpenCode Go works out of the box: base URL
+  `https://opencode.ai/zen/go/v1`, model `deepseek-v4.1-flash`; Coursy adds the required
+  `x-opencode-session` header automatically ([design](docs/OPENCODE_GO_LLD.md)).
+- **Transcription** order in `auto` mode: existing subtitles → local FluidAudio (macOS) → Whisper API.
+- **Interview**: prep timer, max answer length, strictness.
+
+Enrichment is opt-in per course: check **Enrich this course** in the study setup (or start it from
+the Enrichment tab). Once a course is opted in, opening a lesson enqueues it and prefetches the next
+two, with an optional **Enrich course** batch run. Pause/resume/cancel and retry are always available;
+the home page shows a live queue for every active course.
+
+## What it generates
+
+| Artifact | Where |
+|---|---|
+| Lesson summary + key points | Enrichment tab |
+| Scene thumbnails (click to seek) | Enrichment tab |
+| Practice: MCQs (instant feedback) | Enrichment tab |
+| Voice/typed mock interview with follow-ups and grading | Enrichment tab |
+| Study plan from your goals and time budget | Plan drawer |
+| Section rollups + master notes | Plan drawer → Notes |
+| Markdown export bundle | Plan drawer → Export |
+
+## Spaced repetition
+
+Practice generation also extracts 3–8 **concepts** per lesson and tags every question with
+one. Finishing a quick check records per-concept evidence; concepts then resurface on a
+`1/3/7/14/30/60`-day schedule (adaptive by default, `fail → tomorrow`, `hard → ×0.6`,
+`good → next`, `easy → skip one`). Practice sessions never move the schedule — only
+scheduled/manual reviews do.
+
+| Surface | Where |
+|---|---|
+| Revision schedule rail (due now + 14-day agenda) | Home → right rail |
+| Review dialog (MCQ + confidence → mastery/next due) | Home → Revision schedule · `coursy revisions` in the terminal |
+| Concept mastery, performance curve, improvement insights | Stats |
+
+Settings (`/api/settings`, `settings` table): `learning_preset`
+(`relaxed|standard|intensive|custom`), `learning_steps`, `learning_adaptive`,
+`learning_daily_target_min`, `learning_preferred_time` — global with per-course overrides.
+Full design: [`docs/LEARNING_ENGINE_LLD.md`](docs/LEARNING_ENGINE_LLD.md).
+
+## Development
+
+```bash
+npm install
+npm run dev        # server on :4257 + Vite dev client
+npm run build      # production build (client + server)
+npm run doctor
+```
+
+Data model and architecture: [`docs/ENRICHMENT_MERGE_LLD.md`](docs/ENRICHMENT_MERGE_LLD.md).
+
+## Testing
+
+**Unit (no API keys needed).** Scheduler, mastery EMA, review engine, concept
+normalization and UUIDv7:
+
+```bash
+npm run test:unit
+```
+
+**Automated (no API keys needed).** Builds both workspaces, generates a synthetic course with
+ffmpeg (2 scene cuts, an `.srt` sidecar, a text lesson), runs a local mock OpenAI-compatible
+server, and exercises the full pipeline through the real HTTP API:
+
+```bash
+npm run test:e2e
+```
+
+90+ checks cover: scan → queue → extract → subtitle/Whisper transcription → align → summarize →
+practice; persona/goal prompt injection; study plan; typed and voice interview turns with
+follow-ups; pause/resume; dry-run without a key; section rollups; master notes; export; plus
+enrichment consent gating (prefetch skipped until opt-in), the live queue payload, and course
+deletion (DB cascade + on-disk cleanup).
+Fixtures and the test database are kept under `$TMPDIR/coursy-e2e` for inspection.
+
+CLI lifecycle, logging, rotation and config round-trips are covered by:
+
+```bash
+npm run test:cli
+```
+
+**Manual (real browser).**
+
+```bash
+npm run dev
+# open http://localhost:5173
+```
+
+1. `Settings → AI enrichment`: add your LLM key and press *Test*. Optionally set the FluidAudio
+   binary path for local macOS transcription.
+2. Drop a course folder path on the home page (or run `node bin/coursy.mjs play <path>`).
+3. The full-screen **study setup** opens: persona (level, weak areas), course goal (struggles,
+   deadline), then the enrichment opt-in with a first-lesson or whole-course scope, and finally the
+   study plan. Nothing is enriched until you check the opt-in.
+4. Open the first lesson — enrichment follows your opt-in. Watch `Enrichment` for the summary, scene
+   thumbnails (click one to seek the video), MCQs and the mock interview (allow microphone access
+   to answer out loud). Use `Plan` for rollups, master notes and the markdown export, and `Setup` to
+   change your profile, goal or consent later.
+5. Check `node bin/coursy.mjs doctor` for ffmpeg/FluidAudio/LLM readiness, and
+   `node bin/coursy.mjs enrich <path>` for a headless full-course run. Remove courses from the
+   card `⋯ → Remove course` menu or with `coursy remove <id|slug>`.
+
+To test the real FluidAudio path, set the binary once:
+
+```bash
+export FLUIDAUDIO_BIN="/path/to/course-extractor/vendor/FluidAudio/.build/release/fluidaudiocli"
+```
+
+
+## License
+
+MIT