Cramfast product spec

Status: implemented and deployed (version 4, 16 October 2026; study modes, courses with exams, studying together, typed uploads, starting from a name, research papers and example comparisons added 17 October 2026; critical user journeys, goals, Home, teaching, help on demand, explainers and past exams as tests, section 2, 18 October 2026; bringing your own material, building with review, forking and publishing guides, and the rest of the instructor's flow, sections 2.8 and 2.10-2.13, all built 19 October 2026; every journey has a live check and a demo, section 2). This document describes what the product does, the journeys and screens, every data type behind them and how each one is drawn. The pipeline that produces the data (stages, models, checks, costs) is in PIPELINE_DESIGN.md. The fuller design that v4 is built towards, with phone and desktop wireframes and the open questions, is the UI spec and user journey; section 10 lists what of it is not built yet.

1. Goal and principles

A student with an exam in days uploads their course material and wants to know what to study, in what order, to score as well as possible in the time they have.

• Exam first. Every concept carries a predicted share of the exam. The roughly 20% of concepts that carry most of the marks (the core) are taught first; supporting and detail concepts are further levels.
• Two ways to study, one set of content. Follow along goes through each lecture as it was given (an overview of the whole deck first, then every slide explained); Learn re-teaches the course as a short curriculum of modules at the depth the student chooses. Both sit on the concept graph and share one question bank.
• Learning and testing are always separate. Reading never contains questions. Every lecture and module has its own Test yourself; questions use whichever verifiable format tests the skill best (choose one, select all, numeric, short answer, order, match, explain), all graded by code.
• Learn in cards, look up in pages. Anything with an answer, a reveal or forward motion is a card in a session. Anything a student scans, searches or returns to (map, concept page, notes, progress) is a page. Both draw the same typed content.
• Grounded and attributed. Lessons are built on the course's own facts and cite them; every fact cites the slide blocks it comes from. Accurate general knowledge of the subject may be added where it helps (a definition the slides assume, a standard example), and is shown as "General knowledge" instead of a page chip, so the student always knows where a statement comes from.
• The model fills typed slots; the UI owns the layout. Content arrives as typed forms with word limits that fit a phone card. A part that does not fit is dropped, never squeezed. Inside text fields the model writes Markdown and LaTeX maths, which Cramfast draws itself; it never writes markup, layout or styling.
• One schema for every subject. Concept kinds, fact roles and block types describe structure (a process, a rule, a comparison), not subject matter.
• Calm and honest. No points or badges. "Secure" means predicted recall of 90% or better now, so it decays without practice.

2. Critical user journeys

Everyone who opens Cramfast wants one of a small number of things. A journey is supported when someone can finish it from the home screen without knowing the app's words for its parts (module, bundle, tier). This section lists them; sections 3 and 4 describe the parts they use. Status: Built, Partial (what is missing is named) or Missing.

2.1 Goals

A person says what they want when they start a course, in a few taps, and can change it later. A course can have several goals at once for the same person (learn it over the term and pass the midterm), and a single session can have its own goal ("just lecture 3", "the midterm", "what's due"). Goals belong to a person in a course: the owner's, and each member's or visitor's (a share link offers the owner's goals as defaults).

When goals are combined, the plan blends them: an exam's weight grows as its date nears (it leads from 14 days out, and is all there is in the last 2 days); otherwise the other goal's ranking leads.

2.2 Starting with nothing but a question

2.3 Starting with material

2.4 Exams

2.5 Learning over time

2.6 Teaching

2.7 Studying with others

2.8 Shaping a guide as its instructor

An instructor or tutor making a guide for their students needs more than the student-side tools (2.6): control over what students see and when, the guide's structure, how it is written, and the questions. The person who makes the guide owns it (below). Today those tools exist as scattered single actions (Teach it as, Suggest a change, Fill a gap, preview). This journey gathers them, and adds the missing ones, into one process the instructor walks through once after the first build and returns to during the term.

Principles. Every step is optional and starts from a good default, so a guide is usable without doing any of it. Students see only what the instructor has published. Anything that rewrites text shows its price before it runs. An instructor's own edits are never overwritten by a later update or rewrite.

The flow (Shape this guide, from the author's home; a stepper that remembers where they got to):

Journeys:

As built (18 October 2026). Shape this guide (owner sidebar) has four tabs. Concepts: the hierarchy as a tree; per concept its tier (with the prediction shown), its share of the exam in percent (the rest keep their proportions), its name and its topic; new topics. Applied each time the course map is loaded, over the stored map, so each change can go back to the prediction; no model call, and every view follows at once. Outline: each change becomes an owner edit on the pending update (editions.py actions plus rename_module, order_concepts); a rename or reorder rewrites nothing. Presentation: options per scope rendered into one standing instruction for that scope (shown to the owner as "The writer is told…"); a narrower scope adds to a wider one. Update: the pending update with every change, its price, Apply. In Learn and Follow along the owner can select any passage and Steer this passage (quick instructions plus their own words); it becomes a request aimed at that part with the passage quoted.

Build order for this journey: (1) steering concepts, outline and presentation, and precise feedback (G1-G3, built first because instructors asked to steer the content and its look most); (2) draft and publish, direct edits, locks and the review queue (G4); (3) question curation and assessments with dates (G5, G6); (4) the class view linking to fixes (G7).

Who shapes a guide. A tutor or instructor who makes a guide owns it, independently: they upload or start it themselves and every step above is theirs. There is no shared editing of one guide (no editor role); someone else who wants to change a guide makes their own.

2.9 Build order (all five built 18 October 2026)

In this order, each usable on its own:

1. Goals and one home. Goals with follow-ups (2.1) for owners, members and visitors; a home screen that plans from them (C5, D1, D2) and replaces Today; navigation Home · Study (Learn and Follow along) · Test · Map (with progress) · More. No model calls.
2. Teach it. The author's home (E1), overrides taking effect (E2), preview as a student (E3); members can send tests (F2). No model calls.
3. On demand: ask, explain differently, more questions (B4-B6). About a cent each. The owner can always use them; people on the share link only after joining, and only once the owner sets a daily amount for them (off by default, since share links are public).
4. Quick start: one question, a course link, filling a gap (A1, A5, B7).
5. Past exam as a timed test (C4).

Not now: accounts across devices (D5), calibrating predictions on real results (ExamOutcome).

2.10 Bringing what you already have

Many people arrive with significant prepared material of their own: years of flashcards, a question bank, old quizzes with solutions, a study guide they wrote, a whole course in an LMS. Today every file is read as course material for facts, so a deck of 400 cards is mined and thrown away. The aim: what you bring is used as it is, first; Cramfast fills only the gaps.

Principles.

• Kept as-is. Imported cards, questions and notes keep their wording, answers and marking. They are never rewritten silently; Cramfast may flag a problem ("this card disagrees with lecture 3, slide 12") and suggest a fix, which the owner accepts or not.
• Origin shown. Every item says where it came from: Your card, From your quiz 2, Your notes, Written by Cramfast, General knowledge.
• Coverage visible. Imported items are linked to concepts on the map, so the map can say what they cover and what they don't ("your cards cover 61 of 79 concepts, 88% of the predicted exam"). Fill the gaps writes only for the concepts not covered, in the style of what was brought (card length, question formats, notation).
• Unclear is flagged, not guessed. An item that can't be read reliably (no answer key, two candidate answers, a broken image) goes to a short Check these list, not into the bank.
• Cheap. Parsing costs nothing; linking items to concepts is a small model call per batch. The price is shown before anything is written.
• Nothing is locked in. What goes in can come out (H10).

What people bring, and what it becomes:

Journeys:

How it works. New file roles (Flashcards, Question bank, Answer key or solutions, Reference sheet, Recording, LMS export) beside today's. Each imported item is an authored item with its origin (file, row or page), its concept links, and a lock: the pipeline reads it as evidence but never rewrites it. Links are redone when the map changes. Imported questions grade by code like generated ones, and their answers never reach the browser before grading.

2.11 Building it with you: automatic or reviewed

Today a build runs end to end by itself. That suits a student the night before an exam, but not an instructor, or someone who brought material and wants to steer how it is used. Each build offers:

• Build it for me: as today. Every review below stays available afterwards.
• Build it with me: the build pauses at checkpoints. At each one you see what was made, change what you want, and continue. Do the rest automatically is always there.

Default: with me when the goal is Teach it or the upload includes cards, a question bank or an LMS export; for me otherwise.

Principles. Cheap decisions come before expensive writing: nothing is written until the structure is agreed, and the price of writing is shown at the checkpoint before it. Every checkpoint starts from a good default, so Continue without changes always works. The build remembers where it stopped; leaving and coming back resumes it. Reviewing large amounts has three speeds: everything, only what's flagged (parts Cramfast is unsure of: unreadable slides, diagrams it could not read, statements with weak support, questions whose answer it could not verify), and a sample (check a few; if they're fine, approve the rest).

The checkpoints:

The slide review is one screen: the slide on the left, its notes on the right, with keys on desktop (A approve, S steer, E edit, → next) and swipes on a phone, and a counter ("14 of 40 slides reviewed · 3 flagged left").

Journeys:

How it works. The build already runs in stages (extraction, course map, plan, writing); a checkpoint is a stage that waits for Continue instead of starting the next. Approval states (not reviewed · approved · changed · locked) are kept per part on the edition, and a locked or edited part is carried over unchanged by later updates (the G4 rule). Flags come from checks the pipeline already runs (unsupported statements, unreadable pages, failed answer checks).

2.12 Making, forking and publishing guides

A guide is data (a course map, modules, slide notes, questions, editions and the author's steering), so copying one costs nothing and adapting it costs only what is rewritten. People should be able to take a good guide, make it theirs, and give back. Everyone owns what they make (2.8: no shared editing; someone who wants to change a guide forks it).

Principles.

• Forking is free and instant. It copies content, not people: no members, answers or sessions.
• Lineage is visible. A fork says what it came from and at which edition; an original shows how many forks it has. Credit follows the chain.
• Your changes win. When the original changes, a fork can take the changes or not; its own edits and locks are never overwritten.
• Private by default. Four levels: Private (only the owner), Link (anyone with the share link, as today), Class (joined members only), Published (listed in the library).
• Published means rights. A guide is listed only if what it is built from may be shared: open material (open courseware, open textbooks, arXiv), the author's own notes and items, and general knowledge. Guides built from third-party slides or textbooks can still be shared by link for study, as today. The source audit already records where every statement comes from, so this is checked per guide, not trusted.
• Ranked by learning, not likes. The library orders guides by how much studiers improve (their readiness gains and completion), then freshness and forks.

Journeys:

What it needs. Accounts (D5) come first: an anonymous owner loses everything with their browser, and credit, following and publishing need a person. Creation is admin-only today because a build spends money (about $0.45 on Lightweight, about $20 on Full); forks cost nothing, so they are the way to open up, with a per-person allowance for new builds and rewrites. Library studiers' on-demand help (B4-B6) comes from their own allowance, not the author's. Data: a set's lineage (the original set and edition), visibility, licence; a public library index; a suggestions collection per set; upstream changes found by comparing the original's editions since the fork's base.

2.13 Build order for 2.10-2.12 (all built 19 October 2026, in this order)

Each step is usable on its own:

1. Checkpoints before writing (I2, I6): the build pauses after the map and after the outline, with the price of writing shown. Makes every build steerable before money is spent; reuses Shape.
2. Flashcards in and out (H1, H9, H10 for cards): Anki, Quizlet, CSV; coverage on the map; Fill the gaps.
3. Question banks in and out (H2, H3, H10 for questions), with answer keys and Check these.
4. The review queue (I3-I5, and G4): approval, direct edits, locks; flagged-first and sample.
5. Accounts (D5): the prerequisite for everything after.
6. Forks and visibility (J1, J5, J10).
7. Publishing and the library (J6, J7, J11, J12), with the rights check and moderation.
8. Giving back (J8, J9): suggestions and author stats.
9. Following and remixing (J2-J4): upstream changes, partial forks, merges.
10. Bigger imports (H4-H8, H11, H12, I8): own notes kept, reference sheets, objectives, LMS cartridges, recordings, folders, checking imported items.

Decisions taken while building (19 October 2026), each open to change.

• What may be published: a guide is listed only when every file it teaches was found openly, was written by Cramfast from general knowledge, or is declared by the author as their own or openly licensed (naming the licence); a copyright report hides it until an administrator looks.
• Who pays: creating a course is still for people with Cramfast access (the app is admin-gated); copies, the library and studying are free and public. Opening creation with a monthly allowance per account is the next decision, with accounts (sign-in) beyond one-time device links.
• A copy that takes its original's changes takes them part by part; parts the copy locked or edited keep its own; a presentation the copy set applies the next time those parts are rewritten.
• Imported items with errors are flagged with the course's facts and pages; the owner removes, hides or keeps them; nothing is corrected automatically.

3. What a student brings, and what they do

Every journey below has a live example in DEMOS.md, with a link.

3.1 What they start with

3.2 A course over time

1. New. As 2.1; each stage's progress shows on the Overview, then Today. The first build is published as edition 1.
2. More files later. Added from the sidebar or the Update this guide panel, typed as above. A new lecture is mapped, placed into Learn and given notes; a past exam, homework or syllabus re-ranks what is core without rewriting anything. Only what new material touches is rewritten.
3. Feedback in words. See below. Both together are one proposal.

Update this guide: change a finished guide in words, with more files, or both. The panel sits above Learn and Follow along; its bar shows the edition and, once one is ready, Update ready to review.

• Ask in words. Write what should change and choose what it applies to (the whole guide, a lecture, a slide, a module). Suggest a change on each module, lecture overview and slide opens the panel aimed there. Propose changes reads the request in a few seconds (about a cent).
• Add files. Choose what they are (Lectures or notes, Past exam, Syllabus) and pick them. The panel says the course map is being updated and the proposal appears there in 3 to 10 minutes; the owner can leave and come back. The published guide stays up the whole time: the owner and students keep studying the current edition. A past exam or syllabus re-ranks what is core without rewriting the guide.
• Review the proposal. It lists what new material adds (lectures, concepts, new modules, and any lecture that could not be read into the course map), each edit with a checkbox and a one-line summary, what was declined and why (requests about the app rather than the guide are declined), and the price: how many modules, overviews and slide notes will be written, and about how much. Unticking an edit reprices it. Nothing has changed yet.
• Apply or discard. Apply update writes only the parts the edits and the new material touch, usually in one to two minutes; everything else is carried over unchanged. Discard drops the proposal. If writing stops, the panel says so and Apply again resumes it, with finished parts kept.
• After. Owner and students see the new edition: a What's new note (new modules, modules updated, new lectures; dismissible) and Updated marks on each changed module, overview and slide. Questions kept word for word keep their answers, and answers to replaced questions still count. Earlier editions lists every edition and restores one in a click (restoring publishes it again; nothing is deleted).

Requests are standing: a later rewrite of the same part (for example after more material) still follows them.

3.3 Ways to study

3.4 A course, its exams, and sessions that build on each other

A course is the long-lived thing: its files, its course map, the guide's editions, and each student's answers. Within it:

• Exams. The owner names the course's exams (Midterm: lectures 1-4, 2 November; Final: everything) and marks the one being studied for; anyone on the share link picks their own. The active exam scopes Test, Cram and Progress to its lectures, and its date is the countdown.
• Sessions. Every finished quiz, practice exam, cram, test and Today session is kept (kind, scope, score, minutes, per-concept results).
• Building on the last one. Today, Test and Cram open with Last time: when, what, the score, and the concepts still shaky, with Cram these and Test me on them. Progress lists every session. Spaced review schedules the rest.

3.5 Who uses it

• Owner: everything above, plus updates, sharing, exams, People and Review.
• Visitor (/cramfast/s/<token>, no account): every way to study in 2.3 except updates; their answers and sessions stay in their browser. The owner's answers are never shown.
• Member: a visitor who joined by name under Together; their answers and sessions are stored with the course and visible to the owner (and to the group if they choose).
• Reviewer (/cramfast/compare/?a=<token>&b=<token>): two share links side by side (section 8).

4. Screens

Each view has a URL: ?view=<slug>, plus &set=<id> for the owner and &concept=<id> on the map. Courses built before v4 (no lessons) keep the earlier screens: the map is their home, and concept pages show study pages (UI 2) or the original claim list (UI 1).

4.1 The session

A session is a list of steps planned on the server (plan_session in study_views.py):

1. Warm-up: items whose review is due, most overdue first, at most 25% of the time.
2. New concepts on the chosen level, in path order (tier, then the course's own order), skipping anything already started: an intro card, one lesson card per block, a check.
3. Quiz after every new_per_block concepts (default 3): up to two questions per concept, interleaved so no two in a row share a concept.
4. Recap, always last.

Time estimates: intro 20 s, lesson card 40 s, check or quiz question 30 s, review 15 s, recap 20 s. The player adds two steps of its own: a wrong check inserts a Watch out card (the lesson's traps) and appends the same check once more before the recap.

Every card shares one frame: ✕, ←, progress bar and count on top; concept name · tier · card label; body; citation chips; one primary action pinned at the bottom. Keyboard: Enter/Space continue, 1-4 or A-D choose, F flip, ← back, Esc close, ? shortcuts. Phone: full screen, the action bar sticky at the bottom. Desktop (≥ 1180 px): the card centred at 680 px with the slide behind the current card's facts beside it. The step index is kept in session storage so a reload resumes.

4.2 The concept page (lesson as a page)

Top to bottom: breadcrumbs and position on the path; name, tier, share; the lesson head (summary and the "On the exam" box with stated objectives, in the order the lesson style setting chooses; why it matters; "After this you can"); Study as cards (a session for this concept) and Practise (its check, questions and flashcards); each block in page density with a Flag control; the slide viewer opened on best_page; memory aid; Watch out; concepts folded into this lesson; Connects to; drill down; and Everything the course says, the fact ledger grouped by role (Definition, Parts, Kinds, Steps, Features, What it causes, What causes it, Examples, Exceptions, Contrasts, …), each fact with its slide citation and a Flag control.

4.3 Layout

5. Data model and how each type is drawn

Python models are the source of truth (Pydantic, extra="forbid"). Screen views are exported to TypeScript (web/src/generated/views.ts); fields with defaults are required in the exported types, because the server always sends them. A test fails when the TypeScript is stale.

Source (file) ─ Unit (page) ─ Block (text | figure | table | equation | transcript)
                                     ▲ cited by
Fact (Claim) ── roles per concept ──▶ Concept ── taxonomy parent, syllabus position, objectives
     ▲                                  │
     │ cited by                         ├─ derived relations (from roles)
Lesson blocks, traps, options ◀── Lesson + PracticeSet (per concept)   [lessons.py]
                                        │
Attempt ─▶ review state ─▶ ConceptProgress ─▶ TodayView, SessionPlan  [study_views.py]

5.1 Sources

5.2 The concept graph (graph_contracts.py, concept-graph-v4)

Concept kinds: topic, entity, process, principle, method, quantity, event, person, work, condition, other (CONCEPT_KINDS).

Fact roles (FACT_ROLES) and the relation each yields when it names another concept (of):

Invariants (validate_graph): every claim cites blocks; roles name concepts the claim is about; every concept is placed once and the hierarchy is acyclic; syllabus and objectives name known concepts; objective concepts are never detail; shares sum to 1.

Graphs from earlier versions are read through upgrade_graph (v2's medical vocabulary is mapped to the general one; v3 differs only by fields with defaults); stored records are not rewritten.

5.3 Views

5.4 Lessons (lessons.py, concept-lesson-v2)

One record per concept on the level-1 path with at least 4 facts. A smaller concept folds into the nearest ancestor on the path that has a lesson and is covered there as a points entry.

Lesson: summary (≤ 40 words), why_it_matters (≤ 25), can_do (1-3 × ≤ 15), exam_angle (≤ 30), blocks (2-6), traps (0-3 {wrong ≤ 15, right ≤ 20}), memory_aid (≤ 20), connections (0-4 {concept, how ≤ 8}), best_page, folded.

PracticeSet: check (one choice question), questions (2-5; choice with four options each carrying a reason, or free with a model answer and a 2-5 point rubric when the exam format calls for it), flashcards (2-6 {front ≤ 20, back ≤ 25}). Item ids are <concept id>:check, :qN, :fN.

Rules enforced in code (normalize): citations must name the concept's own (or folded) facts (an unknown id is dropped; a part with no course citation is kept as labelled general knowledge); parts over their word limit by more than 25% are dropped; blocks must be complete for their type; options are shuffled (seeded by item id); claims about what exams emphasise are removed; filler step transitions ("then", "next") are cleared; connections name concepts on the map; a lesson needs at least two valid blocks and a check, or it is repaired once and otherwise skipped.

5.5 Study state (study_views.py)

Grading: POST /api/sets/<id>/attempts (owner, stored) or POST /api/shared/<token>/attempts (visitor, not stored) returns correct and a reveal (the right option, each option's reason, the explanation and citations; or the model answer and rubric). Asking to see a free-response model answer is not recorded as an answer.

5.6 Course plan (course_plan.py, course-plan-v1)

Built after the concept graph by create_course_plan; every part is tagged with the concepts it teaches or tests, and with its source (course, citing fact ids, or general, labelled General knowledge).

Depth: a section's level is its most central concept's tier (core 1, supporting 2, detail 3). A student at depth d sees the sections, questions, traps and cards whose concepts include one at level ≤ d, and the modules that have any; minutes are estimated per depth.

5.7 Editions and revisions (editions.py)

Questions are identified by a hash of their text, so a question an update keeps word for word keeps the answers given to it; answers to replaced questions still grade and still count toward their concepts.

5.8 A course's study records (api.py, together.py, narration.py, start.py)

Mastery from answers (the same rule on the server and in the browser): per concept, answers and right answers to the guide's questions; secure = at least two answers, 80% right, the latest right. Readiness = the predicted exam share of secure concepts over the share of the concepts in scope.

6. Practice from the study bundle

The study bundle (per lecture) keeps its own verified practice: Question (four options with explanations, cognitive level, citations) and Flashcard, linked to concepts through item_concepts. The Practice tab runs these; their attempts count towards progress alongside lesson practice.

7. Settings

8. Share links, compare and feedback

• Share links (POST /api/sets/<id>/share, /share-links): read-only, no account. A link can pin a UI version and study-page mode for courses built before v4.
• Compare (/cramfast/compare/?a=<token>&b=<token>&view=…): two links side by side, one view switch for both (Today, Learn, Follow along, Test, Cram, Map, Progress, Together, Guide), an A/B toggle on phones; labels never name the model. Example pairs loads the demo courses worth comparing (Full vs Lightweight for algorithms and immunology, built at once vs grown over time, found online vs general knowledge, two researchers' papers, one lecture vs six); choosing one says what is compared, so a blind comparison is still made by pasting links. Keep the trailing slash.
• Feedback (POST/GET /api/sets/<id>/feedback): a stored, attributed record with form (flag, comment, override, badge), target (concept, topic, fact, block, item, guide), kind (wrong, unsupported, unclear, missing, too_long, pin_core, exclude, merge_into, move_under, rename, reorder, note, reviewed), note and value. For now feedback is stored and listed under Review; nothing acts on it.

9. Quality method

Unit tests (test_lessons.py, test_graph_pipeline.py, …) use a fake model and check contracts only: citations, limits, invariants, the planner's order and the review schedule. Quality is judged on real builds: an independent model reviewer reads each lesson against the exact facts it may use, lists every unsupported statement and scores faithfulness, exam value, clarity and structure (1-5). Latest results (run 3): immunology 3.83 / 3.58 / 4.25 / 3.67, algorithms 3.83 / 2.83 / 4.0 / 3.83, with every marked answer correct. Position bias and exam claims are fixed; unsupported details in option reasons and the low exam value of recall-style lessons on a problem-solving course are not, and need a per-statement entailment check and subject-aware block and practice rules. See PIPELINE_DESIGN.md, "Quality method and results".

10. Not built yet

• The on-demand steps (ask, explain, more questions, gap cards, checking brought items) have not yet been judged on real courses the way lessons have (section 9); transcription of raw audio and video is tested with a stand-in model only (captions were read live).
• Opening creation to everyone (accounts with sign-in, an allowance per account): decisions in 2.13.
• Accounts: a member moves between devices with one-time links (D5), not a sign-in; /r/ review links; feedback taking effect. (No editor role: each guide has one owner, 2.8.)
• Voice answers in Listen (it reads, the student taps); audio files (it uses the browser's voice).
• Graded work feeding the mastery estimate (it is compared, not merged).
• Fact-to-fact links (same as, elaborates, contradicts) and page roles with figure regions.
• Lessons beyond Level 1; ExamOutcome to calibrate the prediction.

11. Earlier versions