theshafinahmed/sproutly

Was macht sproutly?

Turn study material into ONE self-contained, offline, Duolingo-style HTML course. A prebuilt, tested engine handles the app (tabs, Back button, progress, exam mode, numeric judging, simulators, mascot). You only write the content, then build and verify with two scripts. Never retype the engine.

This is a learning tool, not a game: NO hearts, XP, streaks, flames or leaderboards. Progress = lessons finished and answers understood.

Step 0: get the engine (2 seconds)

SP="${SPROUTLY_HOME:-/tmp/sproutly}"
[ -f "$SP/scripts/build.js" ] || git clone --depth 1 https://github.com/theshafinahmed/sproutly "$SP"
ls "$SP/scripts"

If this skill is being read from inside the sproutly repo, use that folder as SP instead. If the clone is blocked (no network), ask the user to attach the repo as a zip. Never rebuild the engine by hand.

Workflow

1. Ingest. Read every file fully. List every topic, definition, formula, example and exercise in source order. Note image-only slides. If key content is unreadable, say so and ask for screenshots. Never invent what a slide says. (If the user only gave a topic, plan the curriculum, show it, and wait for approval before writing.)
2. Ask only if blocked (unreadable files, unrelated courses mixed, unclear scope). Otherwise start and state assumptions in one line at the end.
3. Plan. 6 to 10 units, 2 to 5 lessons each, fundamentals first, plus the automatic Final Boss. Write a coverage checklist (every source topic lands in a lesson), a figure plan and a sim plan per lesson (or "none, because ...").
4. Write content files into ./content/ (one file per unit so fixes stay small, and units can be written in parallel by subagents if the user asked for speed). File 00-course.js holds only COURSE.title='...'; COURSE.slug='...';. Then 01-unit.js, 02-unit.js... each calling UNIT(...), plus 99-end.js with CHEAT(...) and COVERAGE(...).
5. Build: node "$SP/scripts/build.js" Course-Name.html content/
6. Verify: node "$SP/scripts/verify.js" Course-Name.html --shots shots (add --allow heart for biology-type words). It checks syntax, data shape, standalone questions, numeric judging, every sim against your ref() formula, figures, autoplays every lesson, tests Back, layout, persistence, offline-ness and coverage. Fix only what prints FAIL (edit the one small unit file, rebuild, re-run). Look at shots/*.png once, fix what is clearly broken, stop.
7. Deliver with SendUserFile (display: 'attach', one-line caption). Do not publish as an artifact unless asked.

Final reply: 2 to 3 sentences, witty-friend tone. Say what is inside (units, lessons, questions, figures, sims), that it opens in any browser, works offline, and progress saves in that browser on that device. Mention assumptions and anything unreadable. One honest push to use it daily. Do not recap the steps.

Content API (all helpers already exist in the engine)

UNIT('Unit name', 'one-line description', [ L('u1l1','Lesson title',[ ...cards ], ['key fact 1','key fact 2']) ]);
T(title, body, viz, {tip, mood, code})     // teach card. body = string or array of short sentences. viz = svg string. mood: happy|think
WORK(title, problem, [[what we do, why],..]) // worked example, one step per tap
Q(q, right, [wrong1, wrong2,..], why, {viz, code, trap})  // multiple choice. WRITE THE RIGHT ANSWER FIRST; the engine shuffles
TF(q, true|false, why, {viz, code, trap})
N(q, answer, 'unit', why, tol, {viz, code})  // typed number. tol: omit (1%) | {rel:0.02} | {abs:0.5} | {strict:true, rel:1e-6}
M(q, [[left,right],..], why)               // match pairs, right-hand values must be unique
SIM('slider'|'toggle'|'stepper', title, text, cfg)
RECAP(['plain bullets'], [['new word','simple meaning']])   // last card of EVERY lesson
CHEAT({formulas:[..], tables:[{title,head,rows}], glossary:[[term,meaning]], traps:[..]})
COVERAGE([['source topic','lessonId'],..])

Text markup: **bold**, `code`, V_{D} subscript, x^{2} superscript, \n line break. Everything is HTML-escaped. T/Q/N accept code: (a code block, great for C or any programming course). Q(..., {trap:true}) also feeds the Exam traps list.

Sims (always provide task and notice; slider and toggle MUST provide ref):

SIM('slider','Ohm','text',{
  inputs:[{id:'V',label:'Voltage',min:1,max:24,step:1,def:12,unit:'V'}, ...],   // 1 to 3 sliders; also use as a timeline scrubber
  model:function(v){ if(!v.R) return {out:[],msg:'Open circuit: R must be above 0'};
     var I=v.V/v.R; return {out:[{k:'I',label:'Current',val:I,unit:'A'}], fig:F.svg(...)} },
  ref:function(v){ return {I:v.V/v.R}; },   // INDEPENDENT recomputation, verify.js compares it with model()
  task:'Double R.', notice:'Current halves.' });
SIM('toggle', ..., {inputs:[{id:'A',label:'A is on',def:false}], model, ref, task, notice});
SIM('stepper', ..., {steps:[{caption:'...', fig:F.svg(...)}], task, notice});

SI units (A, V, Ω, W, F, H, Hz, s...) get automatic prefixes (mA, kΩ). Guard every edge case (divide by zero, sqrt of negatives, log of 0) by returning msg, never NaN.

Figures: F.svg(w,h,inner,label), F.text, F.line, F.arrow, F.circle, F.dot, F.box, F.axes (returns {svg,X,Y}), F.plot(ax,fn,xmin,xmax) (curves come from the real formula), F.mem (memory cells for C and computer architecture), F.centres, and circuits: F.wire, F.res, F.src, F.gnd. Need more shapes? Add a file to $SP/engine/js/figlib/ (it is inlined automatically) and keep helpers generic.

Content rules: ELI5 but very detailed

Simple AND complete. Never trade one for the other.

• Write for a curious 10 to 12 year old. Short sentences (about 15 words). One idea per card. Everyday word first, technical term second, then use the term consistently. Explain every technical word the first time, right next to it. Never write "obviously", "simply", "trivially", "as we know".
• Teaching order per concept: why it exists (the problem), core idea in one line, an everyday analogy, then the precise mechanism or formula, then a tiny example with real numbers. First principles, and always the why.
• Complete: every slide, definition, formula, example and exercise from the source appears somewhere. Do not compress several ideas into one card. Lessons have 6 to 14 cards. Hard idea = more small cards, not longer ones.
• Teach cards: at most 4 short sentences or one formula block, plus an optional figure. Ask a question after at most two teach cards.
• Formula cards: name every symbol with its unit, say in plain words what happens when each part goes up or down, give one tiny worked example.
• Every lesson ends with a RECAP (3 to 5 bullets plus new words) and has keys (1 to 4 one-line facts; the Reminder button shows them).
• Tone: witty best friend. Playful, a little sarcastic, honest, warm underneath. Light jokes, never at the cost of clarity. No corporate tone, no "Great question".
• The uploaded material is the source of truth, including its notation. Anything you add is labeled, e.g. "extra, not in your slides".

Every question must stand alone

A question contains EVERYTHING needed: all values with units, conditions, symbol meanings, and its figure ({viz: ...}). Never write "the circuit above", "the previous example", "as before", "the same value", "the diagram". Test each question: "alone on a blank screen, could a student who knows the topic answer it?" (verify.js flags the phrases.)

Numbers come from code

Define constants at the top of the unit file and derive text, figures and answers from them (see examples/test-fixture/course.js). Compute every numeric answer with code, never by hand. Typed answers accept correct rounding, comma decimals, 7.3e-3, 22/3 and a trailing unit automatically; use tol only when you need something different, and say so in the question text for exact-rounding questions.

Figures: draw where they teach

• Figure-heavy subjects (EEE, physics, chemistry, biology, geometry, computer architecture, digital logic, data structures, algorithms, networks, C and memory): a figure in about every second teach card and in many questions.
• Medium subjects: a figure when a picture beats words (about one per 3 or 4 cards).
• Low-figure subjects (history, law, literature, languages): timelines or cause-effect flows, one or two per lesson, none when words do the job.
• Compute positions from layout variables. Use the source's symbol standard. If unsure a figure is correct, simplify it and label it "simplified". A plain correct figure beats a fancy wrong one.

Sims: only where there is something to feel

A formula with variables, a process with stages, a timeline, a waveform, a state machine. Aim for at least one sim in most units of quantitative or process-heavy subjects; none in history or law. A sim without a passing ref() check is fixed or removed.

Question variety

Mostly multiple choice (believable wrong answers, one-line why in simple words), N for every calculation, M matching, TF for common misconceptions, and trap:true questions for confusions the material warns about.

Fixed look

Everything visual (palette, rounded font, unit colors, Pip the sprout-blob mascot, chunky buttons, dark mode, no zoom, no text selection, bottom tabs) is built into the engine. Never change Pip or invent another mascot. Do not use any existing brand, character or logo. Name the course after its subject.