Three Academy Upgrades: Full Spec

Written 2026-08-01. Nothing here is built yet.

The goal these three serve: beat I-CAR for a student with zero knowledge AND for a 20-year technician, in the same course. I-CAR's weakness is that it is one linear path that tests recall once and never comes back. Each upgrade below attacks that from a different side.

Read the storage note at the bottom before planning any video work.

UPGRADE 1: Three Depths on the Same Lesson

The problem

Right now every student walks the same 40 slides in the same order. A first-week student drowns. A 20-year tech is bored by slide 6 and stops taking the course seriously. I-CAR has this exact problem and has never solved it.

What the student sees

At the start of each unit, before the first lesson, one screen:

How much of this do you already know? Nine quick questions. Not graded, nothing saved to your record. It only decides how much detail we show you. [ Start ] [ Skip, show me everything ]

Nine questions pulled live from that unit's ASE categories, mixed difficulty. Then one result screen that routes them:

The result screen never says "you are a beginner." It says: "You already know the basics here. We are going to skip ahead and put you straight on the car."

Inside the lesson, the door changes what renders:

• LEARN IT shows every slide, plus it un-hides the extra plain-language slides (this is where the one-idea-per-slide rule pays off), and the narration stays on by default.
• DO IT is the deck exactly as built today. This is the default and the fallback.
• PROVE IT hides the teaching sections and opens on the lab, the Progress Reviews, and the final quiz. If they miss a review question, the slide that teaches it opens right there, then returns them to the question. This is the key move: an advanced tech only reads the part they actually got wrong.

A permanent escape hatch on every slide. A small control in the gear menu: "Show me more detail" / "Speed this up." A student can change doors mid-lesson and it sticks for the rest of the unit. Never trap someone behind a placement test.

What Mario sees

In dashboard2, on the Class page, a fourth card: Where the class placed. How many students landed in each door per unit. A unit where 80% place into LEARN IT tells you that unit needs more time in class. A unit where half place into PROVE IT tells you they already know it and you can move faster. That is a teaching signal you do not get anywhere today.

How it works on data that already exists

• The nine questions come from the same generateASEExam path the simulator already uses, filtered to the unit's ASE categories (ACADEMY_UNIT_CATS[mod][unit] already maps this). Zero new content authored.
• The door is stored per student per unit in one small Firestore doc, academy_placement/{uid} = { "B5-U2": {door:"prove", score:7, at:<ms>} }. One read on Academy open, one write per placement. Same cheap pattern as question_discovery.
• Which slides belong to which door is a new optional slide field, DEPTH: learn (or do, or prove, default do), read by the same filter in academy-player.html that already strips instructorOnly slides for students. The player already knows how to hide slides from a deck without breaking numbering, and the NOAUDIO work proved we can add a slide field without disturbing narration.
• The wrong-answer jump back to the teaching slide uses the per-slide search index (academy-search-index.js) that already maps a topic to the exact slide that teaches it. That index was built for search and it is exactly what this needs.

Build size

Medium. The router, the placement doc, the depth filter, and the escape hatch are roughly a day. The real cost is content: for the LEARN IT door to mean anything, the simplest lessons need 2 to 4 extra plain-language slides each. That is an authoring pass, not a code pass, and it can be done module by module. Until those exist, LEARN IT and DO IT render identically and nothing breaks. That is the right way to ship it: turn on the router first, add depth over time.

Risks

• A placement test that feels like a test will scare a beginner. It must be visibly ungraded and visibly skippable, and the wording above matters.
• PROVE IT must never let someone skip a safety slide. Any slide the author marks DEPTH: always shows in every door. Safety, PPE, and HV lessons get that mark by default.

UPGRADE 2: Spaced Repetition ("Bring It Back")

The problem

A student passes the B5 battery lab in September. The ASE test is in May. By then it is gone. Every certification course on the market has this hole, including I-CAR. Closing it is the single biggest thing you can do to actually raise pass rates, and it costs almost nothing to build because the content already exists.

What the student sees

A new card on the simulator dashboard, under the streak card:

BRING IT BACK 6 things are ready for review. About 4 minutes. [ Start ]

Six to ten questions, each one drawn from a lesson they finished a while ago. Each question is answered, checked, and explained immediately, exactly like the existing Review practice mode. Nothing new to build in the exam engine.

The schedule per lesson, from the day they complete it: 3 days, then 10 days, then 30 days, then 90 days. If they get a lesson's question right, it moves to the next interval. If they get it wrong, it drops back to 3 days and shows a "Review the lesson" link straight to the slide that teaches it.

The nudge matters more than the feature. The dashboard card, a count badge on the Academy nav item, and an optional weekly email ("7 things are ready, about 5 minutes"). Without a nudge this gets used once and forgotten.

A streak that is worth having. Not days logged in. Days where the queue was cleared. That is a habit worth building and it is honest.

What Mario sees

On the Class page, a fifth card: Retention. Which topics the class is forgetting, ranked worst first, measured as "answered right when first taught, answered wrong on the 30-day return." That is a completely different signal from the existing Weakest Topics card, which only shows what they never learned. This shows what they learned and lost. No other course tells an instructor that.

How it works on data that already exists

• The questions are the existing bank, filtered to the finished lesson's ASE tasks. The lessons already cite their tasks on the asetasks slide, so the mapping is already authored. No new questions written.
• The queue is one Firestore doc per student, academy_retention/{uid} = { "b5-l04": {due:<ms>, step:2, lastResult:"ok"} }. One read on dashboard load, one debounced write per session. Same shape and same cost as the flag locker.
• Lesson completion is already tracked (_completeLesson sets fin and pushes maxReached), so the trigger that puts a lesson into the queue already fires today.
• The jump back to the teaching slide again reuses the per-slide search index.

Build size

Small to medium. This is the best value in the whole document: high impact, almost no new content, and it runs on three things that already exist (the question bank, the task citations, and lesson completion). If only one upgrade gets built, build this one.

Risks

• The queue must be capped (10 per session, hard) or a student who took two months off opens it to 300 questions and quits.
• It must never feel like punishment. The copy is "keep it sharp," never "you forgot this."
• The weekly email needs an unsubscribe and should be off by default until a student opts in.

UPGRADE 3: Photo Evidence on Labs

The problem

The lab rating today is a score and a set of tick boxes. It says the work happened but shows nothing. A shop hiring your student cannot see anything, you cannot settle a dispute months later, and the student has nothing to be proud of.

What the student sees

On the lab results slide, above the instructor rating:

Show your work Take a photo of your panel before Mr. Hernandez rates it. [ Take Photo ] (opens the phone camera directly)

One photo per attempt. It appears immediately as a thumbnail. They can retake it before the rating is saved, and not after. Once rated, the photo sits permanently next to the score, so their own lab history becomes a visual record of getting better: attempt 1 next to attempt 3.

What Mario sees

On the grading slide, after picking the student, their photo loads next to the rubric. He grades looking at the actual work on his phone, which is how he already grades. In the dashboard2 Gradebook, a small camera icon on any row with a photo, and clicking the row shows it full size.

How it works

• Upload target: Firebase Storage at lab_photos/{uid}/{deckId}/{attemptNumber}.jpg.
• Compressed in the browser before upload, to a hard ceiling of 100 KB (Mario's call, 2026-08-01). Do not just pick one quality setting and hope. Resize the longest edge to 1000px on a canvas, encode JPEG at quality 0.80, and then step the quality down by 0.05 and re-encode until the file is under 100 KB, with a floor of 0.45. If it is still over at the floor (a very busy, high-detail photo), drop the longest edge to 800px and run the loop once more. That guarantees the cap instead of averaging near it. A shop photo of a panel, a weld, or a gauge reads perfectly well at 1000px and 100 KB; the detail that matters is shape and finish, not pixel count.
• Verify the result before upload. If the final blob is somehow still over 100 KB, refuse the upload and tell the student to retake the photo rather than silently sending a large file. This is not optional; it is the difference between 2 GB a year and 40 GB a year, and it is what makes uploads finish on bad shop wifi.
• The grade record gains one field, photo: "<storage path>", per attempt inside the existing attempts[] array in lab_grades/{uid}. That array is already capped at 12 entries (first plus latest 11), so photo count is capped for free, and the cap already protects the 1 MB document limit.
• Security rules: a student may write only under their own lab_photos/{uid}/ prefix, only image content types, and only files under 300 KB. The rule is what actually enforces the ceiling, so a bypassed or broken client cannot upload a 12 MB phone original. The 300 KB rule sits deliberately above the 100 KB target so a rare stubborn photo still goes through, but a raw upload never can. Read is the owner or an admin, matching the existing lab_grades rule.
• The portal feed already works. lines[] is positional and the export is already built, so the photo path rides along in the existing JSON export with no schema break.

Build size

Small. It is one upload control, one compression helper, one Storage rule, one field on a record that already exists, and a thumbnail in two places that already render.

Risks

• Photos of people. A student will eventually photograph a classmate. The prompt must say "photo of the work, not of people," and you should be able to delete any photo from the grading slide in one tap.
• Retention is ONE YEAR (Mario's call, 2026-08-01). A photo is deleted 365 days after it was taken. That keeps storage permanently flat at roughly one school year's worth instead of growing every year forever, and it matches how long the work is actually worth looking at.
  • The sweep is a scheduled Cloud Function that runs weekly, lists lab_photos/, and deletes anything older than 365 days, then clears the photo field on that attempt so the Gradebook does not show a broken thumbnail. Deleting the file without clearing the field is the bug to avoid here.
  • The score, the level, the rubric lines and the rep count are NOT deleted. Only the image goes. A student's grade history stays permanent; only the photograph expires.
  • Tell the student so up front. One line under the upload control: "Photos are kept for one year. Save your own copy if you want to keep it." A student building a portfolio should download their own.
• Students without a phone camera on a school computer need the upload to also accept a file picker, which the same control gives you free.

The storage and bandwidth math (the answer to "will this fit")

Student lab photos: not a problem

Both numbers below are Mario's decisions: a 100 KB hard ceiling per photo and a one-year retention sweep.

With the one-year sweep, that 2 GB is the steady state, not a yearly addition. Storage stops growing after year one instead of climbing forever. You stay inside the free 5 GB allowance at up to roughly 120 students a year, and even at 200 students you would be paying pennies a month. The compression loop and the 300 KB Storage rule are what hold the line; without them a single class of phone originals is 40 GB.

Your existing lesson art: not a problem either

Slide images are 685 MB and narration audio is 686 MB, and both are served from Hosting, which allows 10 GB. They do not touch the Storage allowance at all.

Video: this is the one that breaks

Use unlisted YouTube, and the lesson builder already supports it. The video slide type takes a YOUTUBE: field and embeds through youtube-nocookie.com with rel=0, so no cookie is set before play and no unrelated videos appear at the end. Unlisted means it does not appear in search or on your channel, and there are no ads unless you enable them.

Self-hosting is worth it only for very short clips (under about 10 seconds, no audio) that you would rather never leave the site. Those are small enough not to matter. Everything longer goes on YouTube.

One rule that stays regardless: the slide's bullet points must teach the point on their own, so a pulled or network-blocked video degrades to a normal slide instead of breaking the lesson.

Suggested build order

1. Bring It Back (Upgrade 2). Highest impact, lowest content cost, runs entirely on existing data. Ship this first.
2. Photo evidence (Upgrade 3). Smallest build in the document, and it immediately makes the lab rating and the STC portal feed worth more.
3. Three depths (Upgrade 1). Turn the router on early so it is live, then deepen the LEARN IT content module by module. B2 is the module that needs it most, since it is the oldest and was authored before the one-idea-per-slide rule.