Book To Course

---
name: book-to-course
description: Turn a book or document (EPUB, PDF, HTML, DOCX, Markdown, TXT — e.g. a programming course book) into a complete interactive beginner-friendly course delivered as a local web page, with step-by-step explanations, animations, quizzes, chapter tests, flashcards, hints, programming exercises checked by unit tests, and learner progress saved to files. Use this skill whenever the user uploads or mentions a book/ebook/PDF/EPUB/tutorial/lecture notes and wants to LEARN from it, wants a "kurs interaktywny", "kurs z książki", "zrób z tego kurs/naukę", an interactive course, study site, quiz/exercise version of a book, or says to continue/extend an existing generated course ("następny rozdział", "kontynuuj kurs"). Use it even if they don't say "skill" or "course" explicitly but describe turning reading material into something to study interactively. Do NOT use for plain summaries, a single quiz, or translating a book.
---

# Book → interactive course

Turns a source book into a folder that works as a self-contained web course. The learner opens it in a browser, reads
explanations written for a complete beginner, plays with small animations, answers quizzes, writes code that is checked
by unit tests, and their progress is stored in a file next to the course.

The player (HTML/CSS/JS + a tiny Python helper) is fixed and already tested — **your job is the content**: read the
book carefully, then write lessons as JSON files. Scripts do everything mechanical.

```
<course>/
  index.html  assets/  serve.py  start.sh  start.bat  README.md     ← player (never hand-edit; refresh with init_course.py --update)
  content/course.json, content/<chapter-id>/chapter.json, 01-*.json … 99-test.json   ← YOU write these
  exercises/<dir>/  (starter files, tests, exercise.json, _solution/)               ← YOU write these for code exercises
  course/data.js                                                                    ← generated by build_course.py
  progress/progress.json                                                            ← learner progress (written by serve.py)
  .build/state.json, .build/plan.md, .build/source/                                 ← resume info + extracted book text
```

Scripts (all in `scripts/`, standard library only):

| script | purpose |
|---|---|
| `extract_book.py INPUT OUTDIR` | book → chapter Markdown files + `manifest.json` + `outline.md` |
| `init_course.py DIR --extract OUTDIR [--ui-lang CODE]` | create course folder, copy player, create state |
| `course_state.py DIR status\|next\|set\|note\|log` | where the build stands (resume across sessions) |
| `build_course.py DIR [--single-file OUT.html]` | validate lessons, print theory/practice balance, write `course/data.js` |
| `verify_exercises.py DIR` | tests must FAIL on starter and PASS on solution |
| `pack_course.py DIR [--share]` | zip for delivery / later continuation |

## Workflow

Create a task list for the steps below. Use SendUserMessage for short progress notes — the learner-to-be may be away.

### 0. Resuming?
If the user mentions an existing course, attaches a course zip/folder, or says "next chapter": unzip/locate it and run
`course_state.py DIR status`. It prints the next chapter, the notes (terminology, running example, style decisions) and the
log. Continue at step 4 for that chapter. If player files look outdated, run `init_course.py DIR --update`.

### 1. Find the source and settle three things
Look for the book in the attachments (`/mnt/user-data/uploads/`), in the conversation, or on the linked computer. Ask only
what you cannot reasonably decide; otherwise state your assumption and go on:
- **Course language** — default: the language the user writes in (explanations, UI, quiz text). Code identifiers stay in English. The book may be in another language; translating while teaching is expected.
- **Scope** — default: the whole book (front/back matter such as covers, indexes, bibliographies is skipped automatically).
- **Exercise toolchain** (programming books) — default: the language the book teaches, if it is installed here (`which go python3 node …`). If not installed, still write exercises but say they could not be verified.

### 2. Extract and inspect
```bash
python3 scripts/extract_book.py /path/to/book.epub work/extract
```
Read `work/extract/outline.md` and the warnings. PDF exit code 2 means a scanned book — run `ocrmypdf` if available, or tell
the user an EPUB or text-based PDF is needed. PDF extraction is heuristic: when code, tables **or math** look garbled,
rasterize the page (`pdftoppm -r 110 -f N -l N -png`) and look at it, then fix the text from the picture. EPUB/HTML are
the cleanest sources.

**Math-heavy PDFs are garbled more often than prose**, because `pdftotext` maps the math font's glyphs to whatever
Unicode code point the PDF happens to embed — not necessarily the right one. Watch for: Greek letters (`λ`, `θ`, …)
silently vanishing from the extracted text; `=` turning into a lookalike character such as `⫽`; `×`/`±`/`√` turning into
the wrong symbol or disappearing; matrices and multi-line equations collapsing onto one line with their layout lost. A
page that reads fine in prose but has a nonsensical equation ("fica Ax x com algum escalar") is this, not a typo in the
book — rasterize that page and transcribe the formula directly from the image into `$...$`/`$$...$$` (`references/math.md`
has the supported LaTeX subset); don't try to guess the original from the garbled text.

### 3. Scaffold and plan
```bash
python3 scripts/init_course.py <course-dir> --extract work/extract [--ui-lang pl]
```
Write `<course-dir>/.build/plan.md`: the learning arc, one line per planned lesson with the source sections it covers
(this is the coverage map — every substantial section of every chapter must land in some lesson), the exercise idea for each
chapter, the running example if any, and the exercise toolchain. Then fill `content/course.json` (`subtitle`, `description`).
Sizing rule of thumb: one lesson per ~1,200–2,000 source words (at least 2 per chapter), plus one test lesson per chapter.
Record decisions that later batches must respect with `course_state.py DIR note "…"` (term translations, naming of the running example, tone).

### 4. Write the course chapter by chapter
For each chapter (`course_state.py DIR next` tells you which): `set CH in_progress`, then **read the whole chapter file in
`.build/source/chapters/`** (in slices if long) before writing — never write from memory of the topic; the course must reflect
*this* book's content and order. Then create `content/<chapter-id>/chapter.json`, lessons `01-….json …`, a test lesson `99-test.json`,
and `exercises/<dir>/` for code exercises. Before writing the first lesson of a course, read:
- `references/pedagogy.md` — how to explain things to a beginner, theory/practice balance, quiz & test design
- `references/lesson-schema.md` — every block type and field (use only these)
- `references/exercises.md` — designing exercises whose unit tests check the learner's code (read when the book teaches programming)
- `references/examples/` — a complete sample lesson (all block types), a chapter test, and a Go exercise folder with tests and `_solution/` to copy the shape from

After finishing a chapter: `build_course.py DIR` (fix all errors; read warnings), `verify_exercises.py DIR`,
`course_state.py DIR set CH done --note "…"`, add notes for continuity. Keep going to the next chapter.

### 5. Batching without losing your place
Long books don't fit in one go. Work chapter by chapter; **state is saved after every chapter**, so stopping anywhere is safe.
When context grows heavy, or after about 3 chapters in one sitting, run `pack_course.py`, deliver the zip, and tell the user
which chapter comes next and that they can say "continue the course" with the zip attached (or the folder linked). A partially
built course is fully usable: unfinished chapters simply don't appear yet.

### 6. Final checks and delivery
1. `build_course.py DIR` → no errors; practice share per chapter roughly 35–60%.
2. `verify_exercises.py DIR` → all OK. A SKIPPED exercise was not verified: say so plainly.
3. Optional but valuable: serve and look at it (`python3 serve.py --no-browser &`, then a headless browser or the built-in browser) — check one lesson renders and a quiz works.
4. `pack_course.py DIR` and send the zip with SendUserFile. If a folder on the user's computer is linked and they asked for it there, write the course into that folder instead.
5. Tell the user in 3–5 lines: unzip, run `start.bat` / `./start.sh` (needs Python 3) or just open `index.html`; progress lives in `progress/`; what is covered and what is next (if partial). `build_course.py --single-file preview.html` yields one HTML file for a quick look without unzipping (progress then stays in the browser).

## What makes a good result (and why)

- **Whole book, in the book's order.** The learner trusts the course to replace the book. Use the coverage map; mention in the final note anything deliberately left out.
- **Beginner-first.** Assume no prior knowledge of the subject: define each term before using it, one idea per block, concrete example before abstraction, analogies for hard ideas, code traced step by step with the `stepper` block.
- **Own words, short quotes.** Explain in your own words. `from_book` blocks are for short excerpts (≲100 words) or code listings from the book with a source reference; never paste long passages — the course is a learning aid, not a copy.
- **Balanced.** Each lesson alternates explanation and doing. `build_course.py` prints the theory/practice split — if a chapter is far outside 35–60% practice, rebalance.
- **Exercises that can be trusted.** For programming: describe what the program must do and which output it must produce, ship starter code that compiles, and unit tests that fail on the starter and pass on the reference solution — `verify_exercises.py` proves it. A broken test is far worse than a missing exercise.
- **Quizzes teach.** Every question has a hint and an explanation of *why*; wrong options come from real misconceptions, not trick wording.
- **Stable ids.** Give quizzes, exercises and flashcard sets explicit, descriptive `id`s (e.g. `ch03-quiz-slices`). Progress is stored by id; renaming or reordering blocks later would orphan it.
- **No placeholders.** Never ship "TODO", lorem ipsum, or lessons that only say "see the book".

## Variants

- **Non-programming books** (history, language, theory): use quizzes, flashcards, `reveal` prompts, tables, SVG/flow diagrams, and `selfcheck` exercises (write-and-compare tasks with a checklist).
- **Mathematics textbooks**: write equations as `$...$` (inline) or `$$...$$` (display) in any `md`/text field — see `references/math.md` for the supported LaTeX subset. Use a `derivation` block for a worked example that proceeds line by line (one algebraic move per step, each with a `why`); use `stepper` for a numeric walkthrough instead when that reads more naturally. `svg` is still the right tool for geometry and freehand diagrams, not for equations. Practice means `numeric` questions (a typed answer checked within a tolerance — use it instead of `fill` whenever the answer is a number) and `order` of proof steps, not more reading.
- **Language-learning books**: heavy on flashcards, `fill` and `order` questions; keep example sentences from the book short.
- **Figures in the book**: don't copy images; re-draw the idea as an `svg` or `flow` block, or describe it in a `table`.
- **Course language ≠ book language**: translate explanations; keep code and official term names, adding the translation in `terms`.

## Troubleshooting

- `build_course.py` refuses to write `data.js` while errors remain — fix them (messages name file, block and field). `--force` writes anyway (don't use for delivery).
- Page is blank → `course/data.js` missing or invalid; rerun `build_course.py`.
- "Run tests" button disabled → page was opened as a file; use `start.sh`/`start.bat`. The command to run by hand is shown on each exercise.
- Test toolchain missing on the learner's computer (e.g. no Go) → the exercise page says which program is needed; mention installation links in the course intro for the language taught.