Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

docs(readme): show the whole shelf, thank the first thousand stars

yzr3af248c26bef
diff --git a/.gitignore b/.gitignore
index 25044f8..dd0f1d6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,10 +14,7 @@ __pycache__/
/img/readme/*
!/img/readme/logo.png
!/img/readme/logo_light.png
-!/img/readme/papermorph-preview.webp
-!/img/readme/papermorph-preview.mp4
-!/img/readme/physics-pulleys.webp
-!/img/readme/joke-collection.webp
+!/img/readme/*.webp
/books/
/content/
/tools/
diff --git a/README.md b/README.md
index 6d38785..420d31e 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,11 @@
<p align="center">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="img/readme/logo_light.png">
- <source media="(prefers-color-scheme: light)" srcset="img/readme/logo.png">
- <img src="img/readme/logo.png" alt="Papermorph" width="600">
- </picture>
+ <a href="https://papermorph.diamonddoge.org/">
+ <img src="img/readme/bookshelf.webp" alt="The Papermorph bookshelf: lessons, picture books, documentaries and interactive pages on a birch shelf" width="420">
+ </a>
</p>
<p align="center">
- <strong>An agent skill that turns textbooks into narrated, interactive web lessons,<br>stories into paper-puppet films, and books into narrated documentaries.</strong>
+ <strong>An agent skill that turns textbooks into narrated, interactive web lessons,<br>stories into paper-puppet films, and books into documentaries, upright shorts and pages you explore.</strong>
</p>
<p align="center">
@@ -16,110 +14,77 @@
<a href=".claude/skills/papermorph/SKILL.md">Read the Skill</a>
</p>
-<p align="center">
- <a href="https://papermorph.diamonddoge.org/">
- <img src="img/readme/papermorph-preview.webp" alt="Pulleys in Elementary Physics, a quiz answered wrong and then right, and paper puppets with subtitled lines from Joke Collection" width="880">
- </a>
-</p>
-
-## What you can make
-
-| You give it | You get | On the shelf |
-|---|---|---|
-| A textbook PDF (maths) | Lessons where formulas and diagrams change step by step as the narration explains, with quick checks and chapter practice that grade the maths, not the string | [Elementary Algebra](https://papermorph.diamonddoge.org/elementary-algebra/) (68 chapters), [Elementary Mathematics](https://papermorph.diamonddoge.org/math-notebook/) (23) |
-| A textbook PDF (science) | Illustrated scenes with acting characters and camera work, plus the same quizzes | [Elementary Physics](https://papermorph.diamonddoge.org/science/) (9 chapters and a sample) |
-| A story, a joke or a fairy tale | A short film of paper puppets in front of sets drawn in code or painted by an image model, with voices, subtitles, sound effects and music | [Joke Collection](https://papermorph.diamonddoge.org/joke-collection/) (7 episodes), [Little Red Riding Hood](https://papermorph.diamonddoge.org/little-red-riding-hood/) |
-| A book or an idea | A narrated documentary of public-domain engravings, paintings and maps, moved in step with the voice, with music | [Madness and Civilization](https://papermorph.diamonddoge.org/madness/) (10 minutes) |
-
-<p align="center">
- <a href="https://papermorph.diamonddoge.org/science/ch12/"><img src="img/readme/physics-pulleys.webp" alt="Elementary Physics: one fixed pulley changes the direction of the pull; two pulleys halve the force" width="49%"></a>
- <a href="https://papermorph.diamonddoge.org/joke-collection/ch03/"><img src="img/readme/joke-collection.webp" alt="Joke Collection: paper puppets on a painted farm, foreign lines with English subtitles" width="49%"></a>
-</p>
+> **1,000 stars.** Papermorph passed a thousand stars this week. Thank you to everyone who starred it, tried the Skill on their own books, filed issues and sent pull requests. The first roadmap is done; the next one is being worked out ([below](#roadmap)).
Everything is a static web page: no server, no database, no account. A book is a folder you can host anywhere.
-## Get started
-
-Install the Skill in your project:
-
-For Claude Code:
-
-```bash
-npx skills add DozenTwelve/Papermorph --skill papermorph --agent claude-code
-```
-
-For OpenCode:
+## On the shelf
-```bash
-npx skills add DozenTwelve/Papermorph --skill papermorph --agent opencode
-```
+### Lessons, from a textbook PDF
-Then, in Claude Code or OpenCode:
+Formulas, diagrams and scenes change step by step as the narration explains, with quick checks and chapter practice that grade the maths, not the string.
+[Elementary Algebra](https://papermorph.diamonddoge.org/elementary-algebra/) (68 chapters) · [Linear Algebra](https://papermorph.diamonddoge.org/linear-algebra/) (40, planes you can drag in 3D) · [Elementary Mathematics](https://papermorph.diamonddoge.org/math-notebook/) (23) · [Elementary Physics](https://papermorph.diamonddoge.org/science/) (9)
-```text
-/papermorph
-```
-
-When you clone this repository, the `/papermorph` command is already available to OpenCode through `.opencode/commands/papermorph.md`. If you installed the skill globally instead, create the same command in `~/.config/opencode/commands/papermorph.md` (see [OpenCode commands](https://opencode.ai/v2/docs/commands)).
+<p align="center">
+ <a href="https://papermorph.diamonddoge.org/linear-algebra/ch12/"><img src="img/readme/linear-algebra.webp" alt="Linear Algebra: three equations become three planes in 3D, drawn in one by one" width="49%"></a>
+ <a href="https://papermorph.diamonddoge.org/science/ch12/"><img src="img/readme/physics.webp" alt="Elementary Physics: one fixed pulley changes the direction of the pull; two pulleys halve the force" width="49%"></a>
+</p>
-OpenCode discovers the skill in this repository's `.claude/skills/papermorph` directory as well, so no copy is needed when working from a clone.
+### Picture books, from a story, a joke or a fairy tale
-It finds the PDF in your project (or asks for your story), tells you what kind of book it is, suggests a chapter to try first and how much animation it needs, and offers a recommended option at every step. Your choices are saved in `style.json`, so every later chapter is made to the same style.
+Paper puppets in front of sets drawn in code or painted by an image model, with voices, subtitles, sound effects, music and camera work. Young readers can tap things in the picture to hear their names.
+[Joke Collection](https://papermorph.diamonddoge.org/joke-collection/) (7 episodes) · [Little Red Riding Hood](https://papermorph.diamonddoge.org/little-red-riding-hood/)
-You need [uv](https://docs.astral.sh/uv/), ffmpeg, and Playwright's browsers (`uv run --with playwright playwright install chromium firefox`). Narration uses Edge TTS (online) or Kokoro (local), free. A few steps are paid, optional and need an API key: painted sets for picture books (OpenRouter or OpenAI), and ElevenLabs narration and clips made from a still for documentaries ([OpenRouter](https://openrouter.ai/)). Everything else runs without one.
+<p align="center">
+ <a href="https://papermorph.diamonddoge.org/joke-collection/ch03/"><img src="img/readme/joke-collection.webp" alt="Joke Collection: paper puppets on a painted farm, cutting between close-ups" width="49%"></a>
+ <a href="https://papermorph.diamonddoge.org/little-red-riding-hood/ch01/"><img src="img/readme/red-riding-hood.webp" alt="Little Red Riding Hood: in the meadow, tapping the sun and a cloud shows and says each word" width="49%"></a>
+</p>
-## How it works
+### Documentaries and upright shorts, from a book or an idea
-**Textbooks:** the PDF is split into chapters → each chapter gets a beat plan and narration → the narration is voiced, and every word gets a time → the picture is laid out as a storyboard first, then animated in time with those words → quizzes go between the steps → the model watches its own output (contact sheets, overlap and blank-frame checks, end-to-end tests) and fixes what it sees.
+Public-domain engravings, paintings, maps and charts, moved in step with the voice, with music. A documentary can be recut as a series of upright shorts for a phone feed.
+[Madness and Civilization](https://papermorph.diamonddoge.org/madness/) (10 minutes, and 4 shorts) · [The Pandemic](https://papermorph.diamonddoge.org/pandemic/) (7 minutes, 6 shorts and a scroll story)
-**Picture books:** your telling becomes a script and a shot list → puppets and sets are built (or painted) once and reused across episodes → voices, mouth shapes, sound effects and music are made and joined per scene → scenes are filmed in parallel → review rounds (a director, picture reviewers and a sound reviewer) send scenes back until they hold up next to approved episodes.
+<p align="center">
+ <a href="https://papermorph.diamonddoge.org/pandemic/ch01/"><img src="img/readme/pandemic.webp" alt="The Pandemic: a world map and charts of cases and deaths as the Delta wave rises" width="73%"></a>
+ <a href="https://papermorph.diamonddoge.org/pandemic-shorts/ch01/"><img src="img/readme/pandemic-short.webp" alt="The Pandemic as a short: Wuhan closes at 10:00 while a clock and a counter run" width="23%"></a>
+</p>
-**Documentaries:** the source becomes an argument, a script and a storyboard → public-domain pictures are found, their licences recorded, and treated to one look → the narration is voiced and music laid under it → the beats are built in step with the words → a director pass checks every beat against the narration.
+### Pages you play
-Large chapters can be made by a team of subagents, each step on the model that suits it ([core/team.md](.claude/skills/papermorph/references/core/team.md)).
+A film can stop and hand the reader the next move, and a map can be walked a year at a time.
+[Shooting an Elephant](https://papermorph.diamonddoge.org/shooting-an-elephant/) (Orwell's essay; you hold the rifle) · [Time of the Magicians](https://papermorph.diamonddoge.org/time-of-the-magicians/) (Europe 1919–1929, four philosophers on the map)
-## The player
+<p align="center">
+ <a href="https://papermorph.diamonddoge.org/shooting-an-elephant/"><img src="img/readme/elephant.webp" alt="Shooting an Elephant: where to aim, then the view through the rifle sight, click to fire" width="49%"></a>
+ <a href="https://papermorph.diamonddoge.org/time-of-the-magicians/"><img src="img/readme/magicians.webp" alt="Time of the Magicians: a map of Europe in 1919, the four philosophers walking their routes" width="49%"></a>
+</p>
-Every book plays in the same player: pause anywhere, step back and forth, click a step to jump there, speed control, captions, keyboard shortcuts, and progress saved per book. Interface text follows the book's language (`<html lang>`: English, Russian, Chinese and Japanese are built in); foreign lines in a film are subtitled. Formulas can be written in LaTeX (MathJax, copied only into the books that use it).
+## Get started
-The player engine lives in [`engine/`](engine), apart from the Skill, and every book keeps its own copy, so a book never breaks when the engine changes. To update the books, or to use your own fork:
+Install the Skill in your project, for Claude Code or OpenCode:
```bash
-python3 .claude/skills/papermorph/scripts/engine.py site # sync every book in site/
-python3 .claude/skills/papermorph/scripts/engine.py site --from you/your-fork@main
+npx skills add DozenTwelve/Papermorph --skill papermorph --agent claude-code # or --agent opencode
```
-Engine versions are tags (`engine-v2`, `engine-v2.1`, …); a new major number means a book may need a change, described in its [release notes](https://github.com/DozenTwelve/Papermorph/releases). Outside this repository, `engine.py` syncs from the latest compatible release, now `engine-v2.8`. Since `engine-v2` the maths helpers (number lines, tiles, planes, the number-set diagram) are in `lib/math.js`: a chapter that uses them loads `../lib/math.js` right after `engine.js`, and `lint.py` names the chapters that need it. `--from DozenTwelve/Papermorph@engine-v1` keeps the earlier engine.
-
-## Video and LMS export
+Then type `/papermorph`. It finds the PDF in your project (or asks for your story), tells you what kind of book it is, suggests a chapter to try first and how much animation it needs, and offers a recommended option at every step. Your choices are saved in `style.json`, so every later chapter is made to the same style.
-With the site served locally, any chapter or episode renders to a 1080p MP4 with an `.srt`:
+In OpenCode, a clone of this repository already has the command (`.opencode/commands/papermorph.md`) and the Skill; with a global install, copy that file to `~/.config/opencode/commands/`.
-```bash
-uv run --with playwright --with numpy .claude/skills/papermorph/scripts/export.py ch12 \
- --url http://localhost:8765/science/ --link https://papermorph.diamonddoge.org/science/ch12/
-```
+You need [uv](https://docs.astral.sh/uv/), ffmpeg, and Playwright's browsers (`uv run --with playwright playwright install chromium firefox`). Narration uses Edge TTS (online) or Kokoro (local), free. A few steps are paid, optional and need an API key: painted sets for picture books (OpenRouter or OpenAI), and ElevenLabs narration and clips made from a still for documentaries ([OpenRouter](https://openrouter.ai/)).
-Frames are rendered from the lesson clock, so the video matches the page exactly; quizzes stay in the interactive version, and the video ends by pointing there.
-
-For courses, a book can also be packaged for an LMS as SCORM 1.2 or 2004 (`scripts/scorm.py`), and a book can opt in to verified citation links and reviewed question banks ([courses.md](.claude/skills/papermorph/references/lessons/courses.md)). None of this is on by default.
+## How it works
-## Models and cost
+A book is planned before it is drawn: chapters or scenes, then a script, then a storyboard. The narration is voiced and every word gets a time, and the picture is animated to those times. The model then watches its own output (contact sheets, overlap and blank-frame checks, end-to-end tests, a director's review against approved books) and fixes what it sees. Large chapters are made by a team of subagents, each step on the model you choose ([core/team.md](.claude/skills/papermorph/references/core/team.md)). The books on the shelf were made with Opus 5.5, GPT-6.1-Sol and Sonnet 5.5; an illustrated physics chapter costs about $10–18 of model usage.
-The Skill is not tied to one model: the books on the shelf were made with Opus 5.5, GPT-6.1-Sol and Sonnet 5.5.
+Every book plays in the same player: pause anywhere, step back and forth, speed, captions, keyboard shortcuts, and progress saved per book, with the interface in English, Russian, Chinese or Japanese. The player lives in [`engine/`](engine) and every book keeps its own copy, so a book never breaks when the engine changes; `scripts/engine.py site` updates them from the latest release (`--from you/your-fork@main` from your own).
-An illustrated physics chapter costs about $10–18 of model usage. The painted sets of a picture-book episode cost under $0.20.
+Any chapter or episode also renders to a 1080p MP4 with an `.srt`, frame by frame from the lesson clock (`scripts/export.py`), and a book can be packaged for an LMS as SCORM (`scripts/scorm.py`, [courses.md](.claude/skills/papermorph/references/lessons/courses.md)).
## Roadmap
-Ticked items are in the Skill today. The Skill currently goes as far as documentaries and their upright shorts.
-
-- [x] **Maths books:** formulas and diagrams that change step by step, with quizzes.
-- [x] **Science books:** illustrated scenes, acting characters, camera work.
-- [x] **Picture books:** paper-puppet films from a story, a joke or a fairy tale.
-- [x] **Choosing the model for every step**, with defaults that depend on how much animation a book needs.
-- [x] **Documentaries:** narrated films of public-domain pictures about a book or an idea. *Madness and Civilization* on the shelf is the reference film.
-- [x] **Vertical shorts** of documentaries: one point in under three minutes for a phone feed.
+The first roadmap is done: maths books, science books, picture books, a model of your choice for every step, documentaries, and upright shorts. Point-and-read, a rifle, a map and a scroll story came along the way. The next roadmap is being worked out; ideas are welcome in [Discussions](https://github.com/DozenTwelve/Papermorph/discussions).
## FAQ
@@ -131,16 +96,14 @@ Ticked items are in the Skill today. The Skill currently goes as far as document
Fixes to the Skill and the player are welcome. Please don't open pull requests that add a copyrighted book, its PDF, or lessons made from one. Agents and people changing the repository: start with [AGENTS.md](AGENTS.md).
-## Try the examples locally
+To try the examples locally:
```bash
git clone --depth 1 https://github.com/DozenTwelve/Papermorph.git
cd Papermorph
-python3 .claude/skills/papermorph/scripts/serve.py 8765 site
+python3 .claude/skills/papermorph/scripts/serve.py 8765 site # then open http://localhost:8765/
```
-Then open [localhost:8765](http://localhost:8765/). (The full history is large; `--depth 1` skips it.)
-
## License
[MIT](LICENSE). The bundled MathJax (`engine/vendor/mathjax`) is under the Apache License 2.0. The MIT licence covers the code. Pictures, recordings and data under `site/` keep their own licences, listed beside them (for example `site/pandemic/img/SOURCES.md`); toned copies of CC BY-SA pictures stay CC BY-SA.
diff --git a/img/readme/bookshelf.webp b/img/readme/bookshelf.webp
new file mode 100644
index 0000000..da20698
Binary files /dev/null and b/img/readme/bookshelf.webp differ
diff --git a/img/readme/elephant.webp b/img/readme/elephant.webp
new file mode 100644
index 0000000..efa1031
Binary files /dev/null and b/img/readme/elephant.webp differ
diff --git a/img/readme/joke-collection.webp b/img/readme/joke-collection.webp
index 853bb8c..57c5b09 100644
Binary files a/img/readme/joke-collection.webp and b/img/readme/joke-collection.webp differ
diff --git a/img/readme/linear-algebra.webp b/img/readme/linear-algebra.webp
new file mode 100644
index 0000000..c0eddfd
Binary files /dev/null and b/img/readme/linear-algebra.webp differ
diff --git a/img/readme/magicians.webp b/img/readme/magicians.webp
new file mode 100644
index 0000000..11c2775
Binary files /dev/null and b/img/readme/magicians.webp differ
diff --git a/img/readme/pandemic-short.webp b/img/readme/pandemic-short.webp
new file mode 100644
index 0000000..7ed352e
Binary files /dev/null and b/img/readme/pandemic-short.webp differ
diff --git a/img/readme/pandemic.webp b/img/readme/pandemic.webp
new file mode 100644
index 0000000..cc779e4
Binary files /dev/null and b/img/readme/pandemic.webp differ
diff --git a/img/readme/papermorph-preview.mp4 b/img/readme/papermorph-preview.mp4
deleted file mode 100644
index de51020..0000000
Binary files a/img/readme/papermorph-preview.mp4 and /dev/null differ
diff --git a/img/readme/papermorph-preview.webp b/img/readme/papermorph-preview.webp
deleted file mode 100644
index 8ea5b1e..0000000
Binary files a/img/readme/papermorph-preview.webp and /dev/null differ
diff --git a/img/readme/physics-pulleys.webp b/img/readme/physics-pulleys.webp
deleted file mode 100644
index 9973ad7..0000000
Binary files a/img/readme/physics-pulleys.webp and /dev/null differ
diff --git a/img/readme/physics.webp b/img/readme/physics.webp
new file mode 100644
index 0000000..4ab8188
Binary files /dev/null and b/img/readme/physics.webp differ
diff --git a/img/readme/red-riding-hood.webp b/img/readme/red-riding-hood.webp
new file mode 100644
index 0000000..f49337a
Binary files /dev/null and b/img/readme/red-riding-hood.webp differ