bavitutor 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+<img src="assets/icon.svg" width="64" height="64" alt="">
 
-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.
+# BaviTutor
+
+Describe what you want to learn. Research agents read curricula, roadmaps and
+textbooks, grade them, and merge them into a **knowledge graph** of small
+concepts with prerequisite links, from ground zero up to your goal. A short
+adaptive quiz finds what you already know, BaviTutor computes the shortest
+path to your goal, teaches each concept with retrieval practice, and keeps it
+in your memory with spaced review.
+
+## Run it
+
+```sh
+npx bavitutor
+```
+
+That's all: it downloads BaviTutor, serves it on <http://localhost:4100> and
+opens your browser. Data stays on your machine in `~/.bavitutor`.
+
+Requirements: Node 24+, [Vite+](https://viteplus.dev) (`vp`), and a logged-in
+[Claude Code](https://claude.com/claude-code) install (the Claude Agent SDK
+reuses its credentials; set `ANTHROPIC_API_KEY` instead if you prefer).
+Generated visuals are rendered and checked in Google Chrome.
+
+### Develop
+
+```sh
+vp install
+vp run dev
+```
+
+Open <http://localhost:5180>. The API runs on port 4100 and the web dev server
+proxies `/api` to it. Data lives in `apps/server/data/bavitutor.db` (SQLite).
+
+### Use it
+
+```sh
+vp run start                         # build if needed, serve, open the browser
+vp run start --port 4200 --no-open   # flags go to the bavitutor CLI
+```
+
+One server on <http://localhost:4100> serves the web app and the API. Data
+lives in `~/.bavitutor`. `vp run build` builds the web app and bundles the CLI,
+API server and workspace packages into `dist/bavitutor.mjs`, with the web app
+in `dist/web`. Unchanged parts come from the Vite+ task cache.
+
+The repository is also an npm package with a `bavitutor` bin, so you can
+start it from anywhere with `npx` or `vpx`:
+
+```sh
+npx /path/to/bavitutor                  # a checkout; run `vp run build` there first
+npx github:Bavlio/BaviTutor             # npm clones and builds it (a minute the first time)
+npx file:/path/to/bavitutor-0.1.0.tgz   # a tarball from `npm pack --force` (builds first)
+vpx /path/to/bavitutor --no-open        # vpx takes the same specs and flags
+```
+
+- Give a tarball as `file:<path>` or `./<relative path>`: npx runs an existing
+  absolute file path as a command instead of installing it.
+- `npm pack` needs `--force` because the repository asks for pnpm
+  (`devEngines`).
+- Git URLs need npm. When `vpx` uses pnpm (outside an npm project), pnpm
+  refuses to build a git-hosted package (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`);
+  use `npx` for those.
+
+| Flag               | Default            | Meaning                                    |
+| ------------------ | ------------------ | ------------------------------------------ |
+| `--port <port>`    | `$PORT`, then 4100 | port to listen on                          |
+| `--host <host>`    | `127.0.0.1`        | interface to listen on (this machine only) |
+| `--data-dir <dir>` | `~/.bavitutor`     | database, plus settings in `<dir>/.env`    |
+| `--no-open`        |                    | don't open the browser                     |
+
+On start the CLI checks for a Claude login or `ANTHROPIC_API_KEY`, looks for
+Chrome (`BAVI_CHROME`, then the standard Windows, macOS and Linux locations)
+and warns if either is missing, and stops with a clear message if the port is
+taken.
+
+### Configuration (environment, `apps/server/.env` in dev, `<data-dir>/.env` for the CLI)
+
+| Variable               | Default             | Meaning                                                    |
+| ---------------------- | ------------------- | ---------------------------------------------------------- |
+| `PORT`                 | `4100`              | port (the API's in dev)                                    |
+| `BAVI_DB`              | `data/bavitutor.db` | SQLite file in dev (relative to `apps/server`)             |
+| `BAVI_MODEL_FAST`      | `haiku`             | grading free text, placement prior, novice                 |
+| `BAVI_MODEL_SMART`     | `sonnet`            | planning, web research, lessons, items, tutor              |
+| `BAVI_MODEL_DEEP`      | `opus`              | merging sources into the knowledge graph                   |
+| `BAVI_RESEARCH_AGENTS` | `4`                 | parallel source researchers per learning goal              |
+| `BAVI_VISUALS`         | `true`              | generate visuals for lesson visual briefs                  |
+| `BAVI_CHROME`          | Windows Chrome path | browser that renders visuals (the CLI finds it if not set) |
+
+The three `BAVI_MODEL_*` variables are only starting points: **Settings → AI models** picks the model, reasoning level and fast mode for each tier, from the models your Claude login offers (listed live through the Agent SDK). Reasoning on _Auto_ keeps BaviTutor's per-step tuning, such as low effort for research planning. Each agent call logs the model and reasoning it ran with.
+
+## What happens when you ask to learn something
+
+1. **Research.** A planner breaks the goal into research angles; parallel
+   Claude agents search and read sources (curricula, standards, roadmaps,
+   textbook tables of contents, courses), extract their topic order and grade
+   each source on a rubric weighted by how fast the field moves. Deterministic
+   readers pull machine-readable sources directly: roadmap.sh roadmaps for
+   software and tech goals (personal use only, as its licence allows), the
+   Common Core coherence map, OpenStax, Exercism, OSSU and MIT OCW. A deep model
+   merges everything into a prerequisite DAG, which is validated (cycles
+   broken, redundant edges removed). Progress streams live to the UI.
+2. **Map.** A layered graph from foundations to goal. Click any concept for its
+   objectives, prerequisites, what it unlocks and which sources teach it. Mark
+   things you know, or **make any concept your goal**: the path recomputes.
+3. **Placement.** An adaptive quiz (Knowledge Space Theory, particle filter,
+   expected-information-gain selection) — usually 6–10 questions — decides
+   what to skip. Unsure results become 1-minute quick checks.
+4. **Lessons.** Motivating problem → no-penalty prequestions → short chunks
+   with a retrieval check after each → worked examples → where it sits in the
+   map → teach-it-back (graded, with a curious-novice follow-up) → delayed
+   recall with re-asks. An in-lesson tutor explains on request and only hints
+   on questions you have not answered yet. Each concept has a **notes** page to
+   re-read before an exam, built from its lesson: key ideas, each chunk's
+   principle, worked examples, common traps, where it sits on the map, your
+   status, and links to go deeper picked from the research sources.
+   "Explain it differently" re-teaches a chunk from another angle, and a
+   failed lesson is rewritten from a different angle aimed at what was missed.
+5. **Review.** FSRS-6 schedules every concept at the retention you choose.
+   Reviews interleave subjects, pick the question level from memory strength
+   (one lower after a lapse, discrimination items against confusable
+   concepts), compress overlapping concepts into fewer items, and give
+   implicit credit to prerequisites. A hint ladder caps how much a helped
+   answer counts. Concepts that keep slipping get flagged with remediation;
+   a backlog switches to triaged catch-up spread over a week; after a long
+   absence a 5-minute check-in replaces the pile. "Just 5" keeps it short.
+6. **Your day.** Home plans reviews first, then as many new lessons as fit
+   your daily time and a two-week review-load forecast. Settings cover daily
+   time, retention, new-concept cap, visuals, a daily reminder, and the
+   Claude model, reasoning level and fast mode for each kind of work. A goal
+   can have an exam date that tightens scheduling. Progress shows durable
+   knowledge, predicted and measured retention, calibration, activity and a
+   review forecast. Lessons resume after a reload, and a break is suggested
+   after about 25 minutes.
+
+The design rests on the research in [`docs/research`](docs/research):
+learning science (≈235 references, with engine rules), adaptive placement,
+source curation and graph building, 3Blue1Brown-style visualization, and an
+analysis of Eero Alvar's AI learning workflow.
+
+## Layout
+
+```
+apps/
+  server/     Effect 4 HTTP API, SQLite, Claude Agent SDK agents
+    app.ts      services, handlers and the HTTP server (makeServer)
+    main.ts     dev entry; cli.ts is the `bavitutor` bin
+    research/   source research pipeline
+    tutor/      question bank, lessons, grader, placement, reviews
+  web/        Foldkit (Elm architecture on Effect) + Tailwind v4 + shadcn tokens
+packages/
+  domain/     Effect Schemas and the HttpApi contract shared by server and web
+  engine/     pure algorithms: graph, path, layout, placement, memory (FSRS)
+  viz/        the `bv` runtime for generated 3Blue1Brown-style visuals (/dev/visuals)
+docs/research/  the research this product is built on
+prototypes/     research prototypes (placement simulator)
+scripts/        prepare: git hooks; builds dist/ when npm installs from git
+dist/           built `bavitutor` bin and web app (vp run build)
+```
+
+## Checks
+
+```sh
+vp check        # format, lint, type-aware lint (TypeScript 7)
+vp run -r test  # unit and story tests
+vp run e2e      # end-to-end smoke tests in Chrome (seeded data, no Claude calls, ~25 s)
+```

package/assets/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#ea580c"/>
+  <text x="32" y="32" dy="0.35em" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, sans-serif" font-size="32" font-weight="600" fill="#ffffff">B</text>
+</svg>