bookSHelf Docs

Hand-curated, AI-enhanced math textbooks — print-grade pages, runnable examples, and voice-narrated animations, built on open sources.

📖 Live at docs.oerbookshelf.app. These pages are rendered from Markdown — the .md files here are the source of truth. After editing one, run npm run docs to regenerate the HTML, then deploy. See 08 · Publishing & Deploy.

These docs are the operator’s manual and the orientation guide for bookSHelf. It serves three readers:

A prospective author deciding whether to run their book through the service → start with What You Get.
A new contributor learning how the repo is wired → start with Architecture.
The operator (you) running the day-to-day procedures → jump to the runbook section below.

What is bookSHelf?

bookSHelf is an AI-powered textbook enhancement pipeline. It takes a raw open textbook (OpenStax, OpenIntro, CK-12, or any scraped/PDF source) and transforms it, section by section, into a polished Student Enhanced Edition: print-grade HTML with worked solutions, interactive try-it-now blocks, hand-tuned figure animations, narrated section videos, slide decks, and an EPUB/accessibility track — then deploys it to the web.

The whole pipeline runs in-session through Claude Code skills plus a set of deterministic Python/Node helper scripts. There is no separate server to babysit; the “orchestrator” is Claude walking a fixed list of steps, and the helpers do the mechanical work (numbering, HTML assembly, publishing, rendering).

Orientation

Page	What it covers
01 · What You Get	The pitch. Before→after, the full feature set, the live catalog as proof, licensing.
11 · Client Intake & Questionnaire	The front door — email template + web form to scope a prospective author’s book and the gaps they want filled.
02 · Architecture	Repo map, data flow, tech stack, the Cloudflare backend, directory reference.

Runbook (procedures)

Page	Task it answers
03 · Content Pipeline	“Turn a raw section into a published page.” The 15-step pipeline.
04 · Figures & Animations	Author a static figure, animate a figure, batch-render, smoke-check.
05 · Section Videos	Build a narrated, multi-scene section-opener video.
06 · Slide Decks	Curate a Slidev deck and export it to editable + rasterised PPTX.
07 · Accessibility & EPUB	Run the a11y gate, KaTeX SSR, and build/validate an EPUB.
08 · Publishing & Deploy	Publish to `docs/`, bump cache, deploy to Cloudflare Pages.
09 · Maintenance & Meta	Memory, session wrap-up, evolution, safe deletion, graphify.
10 · Troubleshooting & Glossary	Common failure modes, fixes, and a term glossary.

Deep references (canonical, kept elsewhere)

docs/PIPELINE_GUIDE.md — exhaustive pipeline internals (chunking, state/resume, performance profiles, system load). These docs summarize and link into it rather than duplicating it.
.claude/skills/ — the source of truth for every procedure. Each SKILL.md is the live spec; these pages cite the skill name.
README.md — project root readme. Note: parts are stale (it describes a Hermes agent and an Electron bookshelf-app/ that are no longer in the tree). Trust these docs over the root readme for current architecture and deploy.

Last reviewed: 2026-06-09 · Maintained alongside the code. When a procedure changes, update the matching skill SKILL.md first, then these docs.