SRS (Spaced Repitation System)

ASYNC REVIEW FLOW (you write the quiz, the user answers it in the web app, you grade it later): 1. create_quiz — write the questions for a due topic. 2. The user answers them in their own time; you are not in that loop. 3. list_quizzes — poll for quizzes they have answered. 4. get_quiz — read their answers alongside the reference answers you wrote. 5. grade_quiz — score each answer, which records the review and deletes the quiz. Use this flow when the user is not in the conversation (a scheduled/cron run, or you are working ahead); use submit_review instead when you can quiz them live in chat. STEP 1 — write a quiz and put it in the user's quiz inbox. Base the questions on the topic's notes/content (get_topic) and mix formats: "single"/"multi" choice for recall, "text" for explanations, "code" for a Java exercise they can run in the browser. 3-6 questions is a good review. ALWAYS supply your reference answers — correct_options for choice questions, expected for text/code — they are stored server-side, are never shown to the user, and come back to you from get_quiz so you grade against what you actually meant days later. The topic must already be learned (mark_learned first), and only one quiz may be open per topic at a time. Nothing is graded and the review schedule does NOT move yet; the user is notified that a quiz is waiting. Do not wait for an answer — end your turn and check back later with list_quizzes.

Create a new subject (a course/grouping that topics can belong to).

Create a topic. Provide lesson material as Markdown in content_markdown (and optional notes_markdown). Set learned:false for "to learn" topics (kept out of the review queue until marked learned); learned:true (default) drops it straight into spaced-repetition using confidence (1-10, default 5). If parent_id is set, the topic inherits the parent's subject.

ASYNC REVIEW FLOW (you write the quiz, the user answers it in the web app, you grade it later): 1. create_quiz — write the questions for a due topic. 2. The user answers them in their own time; you are not in that loop. 3. list_quizzes — poll for quizzes they have answered. 4. get_quiz — read their answers alongside the reference answers you wrote. 5. grade_quiz — score each answer, which records the review and deletes the quiz. Use this flow when the user is not in the conversation (a scheduled/cron run, or you are working ahead); use submit_review instead when you can quiz them live in chat. STEP 4 — read one quiz in full before grading it: every question in order, the expected / correct_options reference answers you wrote at step 1, and the user's answer to each (null until they answer; multi-select answers arrive as a JSON array string). Grade against your own reference answer, but credit a correct answer worded differently. Note each question's 0-based index — that is how you address it in grade_quiz.

Fetch a single topic in full, including summary, notes and lesson content (HTML).

ASYNC REVIEW FLOW (you write the quiz, the user answers it in the web app, you grade it later): 1. create_quiz — write the questions for a due topic. 2. The user answers them in their own time; you are not in that loop. 3. list_quizzes — poll for quizzes they have answered. 4. get_quiz — read their answers alongside the reference answers you wrote. 5. grade_quiz — score each answer, which records the review and deletes the quiz. Use this flow when the user is not in the conversation (a scheduled/cron run, or you are working ahead); use submit_review instead when you can quiz them live in chat. STEP 5 — grade an answered quiz and close the loop. Give every question a score from 0 (wrong) through 0.5 (partially right) to 1 (right), plus feedback written TO THE USER — say what was missing or what to remember, not just "correct". Every question index must appear exactly once; a partial grading is rejected rather than silently scoring the rest zero. This records the spaced-repetition review: your score is folded together with the confidence the user rated themselves, SM-2 advances, and the graded questions are stored in the topic's review history where the user reads your feedback. THE ASSIGNMENT IS DELETED ON SUCCESS — it vanishes from list_quizzes and must never be graded again. Grading a topic also clears its cached auto-generated quiz, so the user's next in-app review asks fresh questions.

List topics due for revision today or earlier (only learned topics), optionally filtered to a subject.

ASYNC REVIEW FLOW (you write the quiz, the user answers it in the web app, you grade it later): 1. create_quiz — write the questions for a due topic. 2. The user answers them in their own time; you are not in that loop. 3. list_quizzes — poll for quizzes they have answered. 4. get_quiz — read their answers alongside the reference answers you wrote. 5. grade_quiz — score each answer, which records the review and deletes the quiz. Use this flow when the user is not in the conversation (a scheduled/cron run, or you are working ahead); use submit_review instead when you can quiz them live in chat. STEP 3 — your work queue. Start a scheduled/cron run with this call. It defaults to status "answered": quizzes the user has filled in that are waiting for you to grade. Pass "pending" to see what they haven't answered yet (chase-up, or decide not to assign more), or "all" for both. Graded quizzes are deleted, so everything returned here is genuinely outstanding and an EMPTY LIST MEANS THERE IS NOTHING TO DO — stop, do not re-grade or re-assign anything.

List all of the user's subjects (course-level groupings of topics).

List topics, optionally filtered to one subject. Returns compact summaries (no bodies).