Html book builder

HTML Book Builder

Build a single, self-contained, offline, interactive HTML document that teaches a topic — better than a printed book on every axis: finding, understanding, remembering, adapting, and deep focus. And unlike most web pages, it must be researched like a book: deep, sourced, and complete. Easy-to-learn must never come at the cost of missing things — the pipeline below exists to guarantee both at once.

Three reference files back this skill. Read them at the phase that needs them:

• references/research-pipeline.md — agent prompt templates, workstream taxonomy, dossier format, verifier instructions. Read at Phase 4.
• references/book-design.md — how expert authors and course designers structure books: backward design, the coverage protocol, the chapter template, page-level rules. Read at Phase 7.
• references/learning-science.md — why each feature works (retrieval practice, cognitive load, dual coding, print-vs-screen), with citations. Consult when you need the "why" or a Sources entry.

The pipeline — run the phases in order

Phase 1 — Ground yourself

Run 2–3 quick orienting searches on the topic. Goal: understand its basic concept, its major sub-parts, its natural shape (a process, a timeline, a set of concepts, or a skill), and roughly how big it is. Do not build or deep-research yet — this exists so your questions in Phase 2 and your research plan in Phase 4 are intelligent rather than generic.

Phase 2 — Tell first, then ask one batch of questions, then stop

Open by explaining the skill in plain words — tell, don’t just ask. Show the intro below, lightly adapted to the topic, as normal response text before any question widget. It is fixed wording on purpose: paste and adapt it, don’t rebuild it from the reference files, and don’t let it grow. A reader who knows what the modes mean answers the mode question in seconds; one who doesn’t gets a wall of jargon.

Here’s what I’ll do: research [topic] properly — several research agents working in parallel, every fact sourced — then build it all into one HTML file that works offline like an interactive book: table of contents, search, quizzes that explain your mistakes, tap-to-define terms, diagrams, and a hands-on widget you can play with.

How deep the research goes is your call:

• Basic — a one-page essentials sheet, about a 5-minute read. The fast path.
• Quick — a compact full book with light research. Good for simple or timeless topics.
• Standard — a full book with solid research. Right for most topics.
• Deep — heavier research. For technical, fast-moving, contested, or high-stakes topics.
• Ultimate — research keeps digging into every subtopic until nothing new surfaces. Far slower and much more expensive; only for books that really matter.

Then propose a sensible default for each question so the reader can just say "go." Cover:

• Audience and prior level — who is this for, how much do they already know?
• Purpose — what should they be able to do or decide afterward?
• Depth and length — quick primer, medium (~15 min), or deep dive?
• Mode and research depth — ask directly: "Basic, Quick, Standard, Deep, or Ultimate? Based on this topic I recommend X." The intro above has already explained what each mode means, so keep the question itself short — the recommendation and one line of why. Basic is the fast path — a one-page essentials sheet instead of a full book; offer it first whenever the reader signals hurry or "just what I need to know" (see Basic mode below). Recommend adaptively among Quick/Standard/Deep for a full book: evergreen/mathematical topics with little factual risk → Quick; typical topics → Standard; technical, contested, fast-moving, or high-stakes topics → Deep. Always mention Ultimate mode last, with an honest warning: not recommended for most books — it burns a very large number of tokens and takes far longer, because research recurses into every subtopic in waves of agents and loops until nothing new surfaces. Never recommend Ultimate; offer it as a deliberate opt-in for books that really matter. The reader decides. If the question widget caps the number of options (many allow only four), the four shown must be: Basic · the recommended tier · the next-most-likely tier · Ultimate — Basic and Ultimate are never the ones dropped; the omitted middle tier stays available as a typed answer.
• Scope and tone — must-include subtopics, anything to exclude, voice, any title/colors to match.

Basic mode — the fast path

When the reader picks Basic, the goal flips from complete to essential: one page, one sitting (~5 minutes), language anyone can follow, built as fast as honesty allows. Speed comes from parallelism and ruthless scope — never from skipping sourcing. What changes:

• Questions: skip the Phase 2 batch unless something critical is ambiguous; default to a general reader with zero prior knowledge, and state your assumptions at delivery.
• Research (Phases 4–5): one parallel wave of 2–4 tightly scoped agents — essentials, pedagogy-lite, plus facts only if the topic has volatile numbers (templates in research-pipeline.md). Lower search counts, same output contract, same dossier rules: Basic is smaller, never sloppier.
• Blueprint (Phase 7): ring-1 only — the 5–9 things someone must know, in dependency order, plus the top 2–3 misconceptions. Everything else is cut, not collapsed.
• Build (Phase 8): a single-scroll page, not chapters: hook → the topic in one sentence → the core concepts as short chunks (plain explanation + one concrete example each) → common pitfalls → a 5-question quiz with explanatory feedback → "go deeper" pointers. One diagram for the central mental model. Keep tap-to-define terms; drop the TOC, search, focus mode, glossary section, capstones, and the widget (include a widget only when it is trivial for the topic).
• Verification (Phase 9): no verifier agent — do the hostile pass yourself, claim by claim against the dossier; still recompute every number.

The file rules never change: one offline .html file, readable with JS off, prints cleanly.

Phase 3 — Set the research goal

Write one short paragraph before planning: what must the reader be able to do when they close this book, and which claims must be verified for the book to teach that honestly. This is the yardstick every later phase is measured against.

Phase 4 — Write the research plan

Read references/research-pipeline.md now. Decompose the topic into research workstreams, scaled by the chosen depth (Quick: 2–3, Standard: 4–6, Deep: 6–8+). Two workstreams are always present, at every depth:

1. Structure & canon — find what any serious treatment of this topic must cover: syllabi, textbook tables of contents, model curricula, standards. Output: a concept inventory (the canon) and the dependency order between concepts. This is the "nothing missing" guarantee.
2. Pedagogy — how people learn this specific topic: documented misconceptions, where learners get stuck, expert teaching sequences, analogies that work. This feeds the pitfalls section and the quiz distractors.

The remaining workstreams cover the topic's content areas, current facts and figures, and real examples/case studies.

In Ultimate mode the plan is recursive: workstreams decompose into subtopic workstreams researched in waves, with a reasoning checkpoint between waves — see "Ultimate mode" in research-pipeline.md.

Phase 5 — Deploy research agents in parallel

Launch one subagent per workstream, all in the same turn, using the prompt templates in research-pipeline.md. Each agent returns structured findings: every fact with a source and date, every number with its formula or origin, misconceptions and examples tagged for reuse. If subagents are unavailable, run the workstreams yourself sequentially — smaller, but same structure, same rules.

In Ultimate mode agents go out in waves: after each wave, run a reasoning checkpoint (dedupe, reconcile, prune, plan the next wave), then launch agents for the subtopics that earned deeper treatment. Loop until a wave stops surfacing new canon-worthy material.

Phase 6 — Synthesize the dossier

Merge all findings into one research dossier — the book's single source of truth. Two rules, no exceptions: no claim enters the book unless it is in the dossier, and nothing enters the dossier without a source. Where findings conflict, resolve the conflict now (prefer primary and recent sources) and record which source won and why. A fact you cannot verify gets cut, not hedged.

Phase 7 — Blueprint the book (backward design)

Read references/book-design.md now. Design before writing any prose:

1. Concept graph: arrange the canon into a dependency order — nothing is used before it is taught.
2. Three-ring triage: tag every concept — big idea (full treatment: worked examples, widget, spiral revisits), important (direct coverage), familiar-only (one line or a "going further" collapsible). Full coverage means every canon concept present at its ring's depth — not everything treated equally. This is how the book stays complete without bloating.
3. TOC + objectives + quizzes: write the chapter list, 2–4 Bloom-leveled objectives per chapter phrased as pretest questions, and the mastery-quiz items mapped 1:1 to objectives — all before any prose. Writing assessments first is what blocks content gaps.
4. Coverage check against the goal: confirm every canon concept and every Phase 3 goal maps to a chapter. Fix gaps now, when they are cheap.

Phase 8 — Build

Write the book to the blueprint, following the chapter template and page-level rules in book-design.md. In Ultimate mode, chapter drafts may be delegated to parallel builder agents, but one integrator — you — assembles the single HTML file, so the book has one voice, one convention set, one CSS/JS system; then loop read-through → fix → read-through until a full pass changes nothing. Every chapter runs: hook problem the reader can't solve yet → objectives as questions → prior-knowledge warm-up → one-concept segments with an inline check after each → worked example, faded steps, independent try → capstone that solves the opening problem (ideally in the widget) → mastery quiz with a review-and-retry path → recap and where these ideas return. Keep the template identical across chapters. Spiral: core ideas resurface in later chapters at greater depth, and later quizzes include 1–2 questions from earlier chapters.

Phase 9 — Verify (adversarial, then technical)

First the verification agent: spawn a separate agent — not you, the author — with the verifier template from research-pipeline.md. It receives the finished book plus the dossier and must: trace every factual claim to a dossier entry, recompute every number from its stated formula and assumptions, check prose examples match the widget's model exactly, and run the two-way alignment audit — every canon concept appears at its ring's depth, and every section traces back to the canon or the reader's stated scope. Fix everything it flags, and rerun the verifier if the fixes were substantial. In Ultimate mode, always loop verifier → fix → verifier until it returns PASS, handing each rerun the previous flag list to confirm the fixes landed. If no subagent is available, do this pass yourself in a separate, deliberately adversarial review — read as a hostile fact-checker, not as the proud author.

Then the technical self-check (below).

Phase 10 — Deliver

Deliver the single .html file. In the closing message: a short list of features included, the research depth used with the number of sources, and anything the verifier caught and fixed. Nothing more — the book speaks for itself.

Technical constraints (these protect the "works forever, anywhere" promise)

• One single .html file. All CSS and JS inline. No external requests, CDNs, web fonts, or trackers — it must work fully offline, opened straight from disk.
• Use localStorage only for remembering preferences (theme, text size), wrapped in try/catch. Page content must never depend on it.
• Responsive (phone to desktop), keyboard accessible, semantic HTML, ARIA labels/roles, a "skip to content" link. Respect prefers-reduced-motion and prefers-color-scheme.
• Graceful degradation: with JavaScript off, the full text is still readable. JS adds power; it is never required to read.
• Include an @media print stylesheet so the book also prints/exports to PDF cleanly.
• Ship valid, error-free JavaScript. Verify it parses before delivering.

Reading experience (how you beat a book at focus)

The screen-versus-paper comprehension gap comes from how screens are usually built — infinite scroll, notifications, links that pull you away. Strip those out and the gap closes:

• Distraction-free by default: clean single column, generous whitespace, no autoplay, no pop-ups, no attention-grabbing motion.
• Typography for deep reading: measure 60–75 characters; body text at least 18px; line-height ~1.6–1.75; strong contrast.
• A "Focus mode" toggle that hides all chrome and shows only the current section.
• "Where am I" cues — a top progress bar and an active-section indicator.
• Light/dark themes and adjustable text size, remembered across visits.

Learning features (include every one that fits the topic)

Each earns its place from the research; add a one-line "Why this feature?" note the first time each interactive element appears.

• Learning objectives up front, phrased as questions the reader tries before reading (pretesting beats plain objective statements).
• Sticky table of contents + scroll-spy, and in-page full-text search with highlighting and next/prev.
• Prerequisites stated at each chapter start, linked to where they're taught.
• Chunked sections — one idea at a time; cap uninterrupted prose at ~2–4 short paragraphs before an interaction appears.
• Tap-to-define key terms revealing definitions in place, plus a glossary generated from those terms (single source of truth).
• At least one inline-SVG diagram per major concept, labels beside the art. Draw the SVG yourself; no image files, no chart libraries.
• "Recall first" prompts and inline checks after each segment — attempt first, explanation as feedback.
• A "common pitfalls" section built from the real misconceptions found in pedagogy research — name the wrong belief, show why it's tempting, correct it.
• Progressive disclosure: depth and familiar-only material behind expandable "going further" details, keeping the main thread clean.
• "Learn more" expansions (Ultimate mode only): every major concept carries a nested, tap-to-open "Learn more" block — subtopic deep-dives inside topics, sub-subtopics inside those where the research went deeper (2–3 levels), each level sourced from the dossier's recursive waves. Built with nested <details> so they work offline and with JS off. The main reading path stays the clean core; Ultimate moves depth into the book instead of cutting it.
• Worked examples before asking the reader to apply anything, with guidance fading across examples.
• An embedded mastery self-quiz per chapter with instant, explanatory feedback and a running score. Wrong options are the documented misconceptions, not filler — so choosing one triggers feedback that corrects the actual confusion. Include 1–2 cumulative questions from earlier chapters.
• Reference material exiled from the teaching path — lookup tables and formal definitions live in an appendix, not mid-chapter.

The interactivity mandate

Whenever the topic allows, build one genuinely manipulable widget — a calculator, simulator, slider-driven chart, sortable table, or interactive timeline — that lets the reader change inputs and see what happens. A book shows one frozen example; you can show infinite ones. Build it in vanilla JS with self-drawn SVG so it stays offline. Chapter capstones should route through it where possible.

Voice, content, and accuracy

• Conversational and second-person ("you"), concrete, with relatable examples. Short paragraphs. Define jargon on first use. The evidence favors this register — it measurably outperforms formal textbook voice.
• The dossier is law. Never state a fact, number, statistic, or citation that isn't in it. State the assumptions behind every number, and use one consistent convention everywhere — prose examples must match the interactive widget exactly.
• Mandatory Sources section in the book's footer: every source from the dossier that survived into the book, with links and a "last verified" date.
• Open with a brief, skippable "How to use this book" note pointing out search, focus mode, the quiz, and key terms.

Technical self-check before delivering

Run after the verification agent's pass, fix anything that fails:

1. JS parses with no syntax errors — extract the script and run node --check in a temp location; clean up after.
2. Every control is wired — each button/slider/quiz option has a working handler; the widget updates live; search highlights; theme/focus/text-size all work.
3. JS-off test: with scripts disabled, the article still reads top to bottom.
4. Accessibility pass: headings nest correctly, controls have labels, contrast is sufficient, keyboard navigation works.

The "better than a book" checklist (all should be true)

Researched with sources, not improvised · complete: two-way canon audit passed · every claim traceable to the dossier · find any word instantly (search) · objectives as pretest questions · test yourself (mastery quiz with misconception-based feedback) · common-pitfalls section · definitions in place + glossary · progress/location cues · focus mode + deep-reading typography · adjustable text and light/dark, remembered · accessible / read-aloud ready · at least one manipulable interactive widget · diagrams drawn inline · prints cleanly to PDF · works offline as one file · (Ultimate only) sourced learn-more expansions on every major concept.

Basic mode is exempt from the book-apparatus items. Its bar: the essentials are complete and sourced, it reads in one sitting, the pitfalls are real misconceptions, and the quiz works.

Reference files

• references/research-pipeline.md — research phases in detail: workstream taxonomy, agent prompt templates, dossier format, verifier agent instructions.
• references/book-design.md — the structural evidence base: backward design, coverage protocol, chapter template, page-level rules, with citations.
• references/learning-science.md — the cognitive evidence base: memory, retrieval practice, cognitive load, multimedia learning, print-vs-screen, with citations.
• references/example-compound-interest-book.html — a complete example book to imitate for layout and vanilla-JS patterns (search, quiz, focus mode, calculator with self-drawn SVG chart). Note: it predates the current spec — it contains a flashcard deck and spaced-review plan, which are no longer part of this skill, and it wasn't built through the research pipeline. Imitate its craft, not its feature list or topic.