# PedsHub — outstanding work Everything requested and not yet delivered. Ordered roughly by dependency, not priority — say which to take and I'll reorder. Updated 2026-09-11 (overnight). --- ## Asked for on 2026-09-11, not yet done Captured so nothing is lost while the article writing runs. ### Sessions and analysis - [x] **Session analysis after a quiz** — `/analysis/session/:attemptId`: rail of latest sessions, the four figures (correct, completed, time per question, total time), a donut, study recommendations, and a paginated performance table with time and peer statistics. Time per question is now recorded (`attempt_answers.seconds_spent`); answers from before that read "—" rather than claiming zero. - [x] **Return to a session rather than being launched into it** — `/quizzes/:id` auto-started, so every link from the history fired a 243-question exam on click. It now shows the session — mode, length, what the clock does — and starts when asked. Session rows and the analysis rail open the session's analysis rather than the raw answer list. - [x] **An unsuspended exam keeps running** — done 2026-09-11. When the clock runs out the exam is submitted with what was answered and the score counts; resuming lands on the result. Settled by whichever notices first (resume, or the sessions list). Previously such attempts were flagged `expired` and hidden from every statistic. Suspending still holds the clock. - [x] **Deleting a session removes its data** — done 2026-09-11. Answers cascade; saved progress and the device lock are cleared; a study-plan block whose only completed attempt is deleted goes back to unfinished. - [x] **Reset all data** — done 2026-09-11. Settings → Your data. Typed RESET, states what goes (sessions, answers, saved progress, plan progress, reading marks, saved questions, question notes) and what stays (account, anything authored, AI conversations); reports the counts afterwards. ### Articles — prose and links - [~] **Third person, impersonal** — 819 imperatives across 348 sections. Nine of ten batches applied (740 imperatives cleared, 79 left in 43 sections); one batch outstanding. `scripts/prose_pass.py` exports, takes rewrites back, and refuses any that lost a cross-reference, changed a number or landed outside 0.7-1.4x length. First and second person were measured at zero and sixteen (sample boilerplate) — neither needed work. - [x] **Smart cross-linking** — done 2026-09-11. First mention per view, lists as jump lists, the 23 titles in more than 5% of articles link from lists only. 3,560 links to 2,191, and the tail with it: Seizures 119 to 48. Re-runnable — it strips its own work and reapplies the rule. - [x] **37 nested cross-references repaired** — `[[363|[[245|reflux]] disease]]` from the first linker pass, which rendered as literal brackets. - [ ] **Clinical view in MDM order** — presentation → differential → diagnosis → management → prognosis/outcome where it adds something. ### Reading and study - [x] **Recommendations by Articles / Disciplines / Systems** — done 2026-09-11. Three groupings over the same answers; Articles is the default. Systems rolls up through the symptom keyword's parent and states its own coverage (1,502 of 2,948 questions). "Practise this topic" works on whichever axis the row came from. - [ ] **Adaptive session** — the design and its weaknesses are written up in `docs/study-recommendations.md`; two defects fixed (a 2,000-row cap that hid a third of the bank, and an O(n·m) category lookup). Still open: ordering uses raw accuracy rather than shrunk readiness, and difficulty is a filter rather than something the session moves along. ### Settings and access - [x] **Settings revamp** — done 2026-09-11. A section list beside one panel, the section in the URL so it can be linked to. The exam objective moved in; the notifications panel went, its one control having switched a reminder scheduler that no longer exists. - [x] **Access as a tree** — done 2026-09-11. `/access`: a person on the left, everything they hold on the right. A granted branch shows its children as covered rather than separately tickable. "Everything" is the moderator role and says so, rather than a wildcard grant nobody could audit. A branch now also covers the articles filed under it — an educator could previously edit a branch's questions but not its reading. - [ ] **Question folders** — collect questions into folders for assignment, the one grantable thing the access tree does not yet cover. ### Media - [x] **Audio and video** — a murmur cannot be shown as a picture. Uploads take MP3/WAV/OGG/M4A and MP4/WebM/MOV alongside images, with their own 60 MB ceiling, and each renders as what it is. - [x] **Editing opens over the grid**, not inside a cell that stretches its column and shoves the neighbours out of line. - [x] **Every figure named by its subject**, with the question number appended only where a subject repeats — a legend a reader sees in an explanation should not be twelve identical words. - [x] **Deleting a figure in use is refused** unless forced, with the count shown. Renaming and moving are safe because the link is the id. - [ ] **Library filter in the picker** is in; a library *rail* in the picker would be better on a wide screen. ### Editor and figures - [x] **Rich editing on the question page** — no new platform needed: Milkdown is already installed and used for articles, courses and the quick modal. - [ ] **Milkdown on the stem and the options**, replacing the plain textareas. Note the stem carries manual-highlight offsets, so check what a WYSIWYG rewrite does to them before switching. - [x] **Many figures per question** — `question_media` links a question to any number of images in the bank, each with a role (stem or explanation), a label the prose can refer to ("Figure 1") and an order. The 346 existing single paths were backfilled and retitled; the filename stays in the caption as provenance. - [x] **Explanation figures as labelled thumbnails** — done 2026-09-11. They open full size and page between each other; a stem figure stays full width. Withheld until answers are revealed, like the explanation itself. - [x] **Figure management in the question editor** — done 2026-09-11. Add from the bank, name, caption, reorder, remove, per role. An uncaptioned figure is called out as one nobody will find. ### Dashboard - [x] **Stats are about questions, not quizzes** — questions seen out of the bank, answered correctly, average score. - [x] **The old performance card is gone** — a per-quiz graph needing two attempts, superseded by the session analysis. - [x] **Vary the greeting** — done 2026-09-11. Four time bands including the small hours, keyed on the date so it holds for a visit and differs between days rather than changing under the reader mid-render. ### Questions I owe an answer to - [x] **What extracted the PDFs?** PyMuPDF (`fitz`) in `pdf_service.py`, with an MD5 skip list for repeated branding images. It pulled every embedded image from all 18 source PDFs, which is why one 767-page document produced 908. - [ ] **How do the study recommendations work?** — walk through the code. - [ ] **How would an adaptive session work?** — design before building. --- ## Design agreed, not built - [x] **AI Mode (RAG chat)** — done 2026-09-10. `conversations` and `conversation_messages` (migration `a5b6c7d8e9f0`), retrieval across sections, articles, questions and cards with the curated-link boost, the ID-citation contract enforced server-side, and `/ai` with a thread rail. Answers cite by number and every source opens; a section citation deep-links into its section. Question sources carry the stem only, so a chat cannot hand away the practice it is meant to prepare for. - [x] **Global search page** — done 2026-09-10. `GET /search` runs every corpus at once and `/search` groups the answer by kind, with section hits listed under the article they belong to and linked to that section. A header box offers "go to this article" or "search everything". Each corpus keeps its own visibility rules — bank predicate and exam scope for questions, the draft rule for articles, deck ownership for cards, library grants for images. The Search / AI Mode toggle waits on AI Mode. ## UI fixes raised 2026-09-10 - [x] **Quiz/test categories removed** — done. - [x] **Sessions list shows only a few** — done, with a link to full history. - [x] **Analysis session rail full-height** — done. - [x] **Articles page layout** — done 2026-09-10. The page is the column browser itself: topics and the articles filed under them share a column, separated by icon, one column per level opened. - [x] **Systems facet duplicates** — done 2026-09-10. 491 redundant "(Parent)" suffixes stripped and 3 sibling pairs merged. Nesting still to do. - [x] **"⚙ Filters2948 questions"** — done. The stylesheet was never imported. - [x] **Category page relationships** — direct vs rolled-up counts, empty-leaf badge, and a desktop hint on small screens. - [x] **Newly created categories now appear** — the bare path 307-redirected to http://, which the browser blocks as mixed content, so the call failed silently. Trailing slash added. - [x] **Image/media page** — done 2026-09-10. Tags and captions show in the picker as well as the bank, libraries have their own rail, and ids sit on every thumbnail rather than only on hover. ## Content and editing - [x] **Study plans have a front end at all** — done 2026-09-10. 13 plans were seeded with an API to serve them and no page that called it. `/study-plans` lists them with progress in blocks; `/study-plans/:id` is one plan. - [x] **Admin can edit study plans** — done 2026-09-10. Create (as a draft), rename, publish/unpublish, delete; add, rename, reorder and remove blocks; move questions between blocks of the same plan; attach and detach reading. Editing is inline on the learner's own page, so there is no second layout to keep in step. - [x] **Study plan blocks carry articles** — done 2026-09-10. Each block shows Articles with a reversible *Mark as read*, then Sessions with Study and Exam mode. Reading progress is per learner and separate from `article_views`: opening an article is not the claim that you finished it. - [ ] **Admin settings page revamp** — currently ugly; needs restructuring. - [x] **Image libraries** — done 2026-09-10. Libraries, per-library grants, tags on the shared vocabulary, and MinIO behind a storage service. - [x] **Media management page (frontend)** — done 2026-09-10. `/media` browses the bank by library, searches by what an image shows, and edits title, caption, alt text, tags and library in place; ids are on every thumbnail because that is what a question refers to, and an image with no caption is called out as one nobody will find. `ImagePicker` replaces the type-a-filename field on the question editor, and an image uploaded from it lands on the question directly. - [ ] **Question folders** — collect questions into folders for assignment and access, alongside category grants. ## Article reading - [x] **Nested sections and per-section collapse** — done 2026-09-10. A section may sit under an earlier top-level one (`parent_id` on the section JSON), the contents rail lists sub-sections under their parent, and an article opens as headings only, each expanding where it sits. Deep links open the target section and its parent. - [x] **Cross-references with previews** — done 2026-09-10. `[[slug]]` or `[[Label|slug]]` in article prose becomes an in-app link that shows title, excerpt and section count on hover, from `GET /articles/preview/{slug}`. One fetch per article per page; no card on touch, where there is no hover. - [x] **Library browsed column by column** — done 2026-09-10. The articles page is now the column browser itself: topics and the articles filed under them share a column, separated by icon. Search still answers with a flat list. - [x] **References** — a section titled "References" is pinned last and styled. The numbered list with in-text superscript markers is deliberately NOT built: "with refernec, but you dont need in text reference". Closing this rather than leaving it open against an instruction. - [ ] **Per-section notes and feedback** — a learner's own note attached to a section, and a feedback channel to the educator. - [ ] **High-yield / key-exam-info toggles** — mark spans and let the reader show or hide them. ## Quiz runner - [ ] **Per-question notes in study mode**, replacing the global notes tab that is currently on the quiz page. - [ ] **Per-question feedback** to the educator. - [ ] **Tutorial mode** — first-run coach marks ("Step 2 of 6", Skip / Next). ## Analysis - [x] **Per-question performance table** — done 2026-09-11 on the session analysis: position, excerpt, difficulty, time, peer percentage; sortable by position / slowest / hardest, ten a page. - [x] **Session analysis** — done 2026-09-11. Sessions and analysis are one page: `/sessions` is the overall picture, `/sessions/:attemptId` one session, the sidebar lists every session. Recommendations grouped by Articles / Disciplines / Systems remain open (see Reading and study). ## Dashboard - [ ] **Overview page for signed-in users** — search hero with Search / AI Mode toggle, "Continue your study", and a study-analysis donut. The current dashboard becomes this; a separate signed-out landing page comes later. ## Taxonomy - [x] **Systems subsystems** — done 2026-09-10. 69 subsystems created, 305 conditions nested; the tree is now System → Subsystem → Condition. - [x] **Cross-system duplicate conditions merged** — done 2026-09-10. 216 names folded to one home each (347 rows removed, 1075 → 786), keeping the other systems as `question_category_links` rather than duplicate rows. - [ ] **114 tied conditions need a human call** — an even split across systems has no evidence-based winner, so nothing was merged. Run `scripts/merge_duplicate_conditions.py` to list them; the largest are Pneumonia, Behavioral Disorder, Intestinal Obstruction, Acute Rheumatic Fever, Hypoxic-Ischemic Encephalopathy. - [x] **Primary categories pushed down** — done 2026-09-10. 1,244 questions promoted from system to condition; 2,730 → 1,486 filed at system level. The system stays as a cross-link so no filter narrows. - [x] **Unfiled questions classified** — done 2026-09-10. 1,170 of 1,486 filed by retrieval + a chooser constrained to the shortlist. 316 remain on a bare system: 301 the chooser declined and 15 with no viable candidate. - [x] **Every question filed below its system** — done 2026-09-10. The last 316 were forced onto their nearest candidate; 0 remain on a bare system. - [ ] **Review the classifier's work** — roughly 3 in 4 were right on a spot check, so expect some wrong. The original system is kept as a cross-link, so a wrong pick never loses a question. Worth an editorial pass. - [ ] **31 questions tie between equally specific conditions** — left alone. - [x] **Real organ systems, and symptoms grouped under them** — done 2026-09-10. The 27 "systems" were disciplines; that tree is now the Topics facet, and Systems is a new flat axis of 16 organ systems. `question_tags` gained `parent_id`/`sort_order` (migration `e3f4a5b6c7d8`), and 726 symptoms are filed under the system they present in. 3,536 stay top-level rather than being forced into an approximate bucket. - [x] **Taxonomy editing screen** — done 2026-09-10. `/categories` is now Taxonomy: five tabs (Topics, Systems, Symptoms, Diseases, Subjects), each with create / rename / reparent / delete-with-move, and "+ Questions" to attach questions from a bank search. Everything added lands in the question bank and quiz builder immediately. - [x] **Article section index backfilled** — done 2026-09-10. The index was empty because `_rebuild_section_index` only runs on save, so articles written before it existed had no rows. 10 articles / 28 sections indexed and embedded; section-scoped question links already worked. - [x] **Grant dimensions** — done 2026-09-10. A grant names any combination of exam, discipline and category, and covers what matches all of them. - [x] **Exam-scoped disciplines** — done 2026-09-10. A tag may be shared (`exam_id` NULL, e.g. Cardiology) or scoped to one exam. Boards Pediatrics and a future Step 1 Pediatrics are separate rows over different content, rather than one label spanning both. Pediatrics is bound to Pediatrics Boards and now covers all 2,948 questions. Facet counts are computed within the active exam and empty facets are hidden. --- ## AI Mode design Retrieval decides what the model may cite; the model only writes prose. 1. Embed the learner's message, search every corpus (`hybrid_ids` already covers questions, articles, sections, cards, media). 2. Put the retrieved rows in the prompt as the *only* permitted sources, each with its kind and id. 3. The model cites by id from that list — `[[article:7#features]]` — never a URL. 4. The server rewrites citations to links and **drops any id that was not retrieved**. A citation the model invented cannot survive. That last step is the safety property, and it is enforced by the system rather than by the model behaving well — the same discipline as the article page no longer printing answers. **Settled: two kinds of link, handled differently.** *Curated* links already exist as tables — `QuestionArticleLink`, `FlashcardArticleLink`, `FlashcardQuestionLink`, `LabReferenceCardLink` — and carry a section id. An educator asserted them, so they are trusted and stored. *Retrieved* links are computed per query by `hybrid_ids` and are not stored at all. They are ranked guesses. The AI uses both: retrieval finds candidates, and a candidate carrying a curated link to another candidate is boosted, because an educator has already tied those two together. Nothing new is stored for citations. The only new tables AI Mode needs are `conversations` and `messages`. --- ## Done this session Hybrid search (full text + BGE-M3, RRF-fused) · embedding provenance and retry job · articles, cards, sections and media as searchable corpora · exams as real data with a per-user active exam · AI-mode matching from description or upload · category management page · tag vocabulary sanitised · question manager with bulk editing · per-category educator grants · full-page question editor · session rail with gradual reveal · articles read as one page · practise-this-topic · continue-study panel · PREP study plans · question version history · exam-scoped disciplines. ## From the 11 Sep recordings — still open - **Quiz player, "let it not be showing when you're taking the quiz"** — the recording does not say what "it" is. Most likely reading: in exam mode the right-hand question rail must not reveal right/wrong as you go (study mode may). Confirm before changing. - **Study plan overview cards** — AMBOSS shows per-block progress bars ("0/6 articles · 0/40 questions"); ours shows a status word. Polish once the block page has been used. - [x] **ArticleSplitView flake** — fixed. It hovered a link, which starts a 350ms timer before the preview card appears; it now focuses instead, which reveals at once. The failures were it losing CPU to the backend suite. - **Third analysis tab "Session analysis"** — AMBOSS lists sessions as a tab; ours are the sidebar, which is what was asked for. Leave unless it comes up.