`/`

` sections, at least one or two ``s > or key-point boxes, covering the high-yield facts, mechanisms, associations, and "do-not-miss" > items of that block. Match the depth of the source material; a guide should stand on its own as a > revision sheet. > > **Link items to their guide.** Most questions and cards should carry a `guide` pointer > (`{ "f": …, "t": …, "s": … }`) into the relevant embedded guide so the app can deep-link from an > item to the right section. A pack where few or no items reference a guide leaves the Topic Guides > reader disconnected — wire them up as you write each item. The `guides` array holds one object per guide: ```json "guides": [ { "file": "Topic_C1_Arrhythmias.html", "title": "C1 · Arrhythmias", "html": " … full guide HTML … " } ] ``` - `file` — **must exactly equal** every `guide.f` that points to this guide. This is how the app resolves a link to the embedded copy (it's an identifier, not a real file). - `title` — shown in the Topic Guides sidebar. **Name it well**: the sidebar sorts intelligently by parsing a leading `Week NN`, `Topic NN`, or bare `NN —` prefix (roman numerals like "KU III" also sort numerically), so titles like `"Week 12 — Arrhythmias"` or `"Topic 03 Adrenal"` order themselves correctly. - `html` — the **complete HTML document** of the guide. It renders in a sandboxed iframe, so it carries its own `

C1 · Arrhythmias

One-line orientation.

Atrial fibrillation — rate control

Irregularly irregular, no P waves → beta-blocker or non-DHP CCB first-line.

``` Embed the full HTML (escaped for JSON) as the `html` value of the matching `guides[]` entry. --- ## 6a. The cram sheet — the LAST guide in every pack **Every pack ends with a one-page cram sheet** as the **final `guides[]` entry**: a dense, print-friendly "night-before" rapid review of the pack's week(s). It is a regular guide (same `{file,title,html}` shape, same dark-mode-safe CSS contract from §6) — just purpose-built as a single high-density revision page. - **Title it** so it sorts last and reads clearly, e.g. `"Week 16 · 9 Cram Sheet"` (use the next number after your last topic guide). `file` key e.g. `"W16_09_Cram_Sheet.html"`. - **Scope = this pack's week(s) only.** One sheet per pack (per week, or per the pack's week-range) — not one giant sheet for a whole course. - **Structure** (mirror `Night-Before_Cram_Sheet.html`): - a top **"do-not-miss / emergency" strip** — the can't-miss diagnoses, red flags, and first actions; - then **compact multi-column topic cards**, each a tight list of **cue → answer** rows (the single highest-yield fact per line: classic clue → diagnosis/next step/drug). Think "everything you'd want on one page the night before," not prose. - **CSS:** dark-mode-safe, variables only (§6) — the legacy standalone Night-Before sheet hardcodes hex; the embedded version must theme cleanly. A multi-column print layout (`column-count`) and a print button are encouraged but optional. - **Linking:** items generally do **not** point their `guide` at the cram sheet (it's a review surface, not a section target) — keep wiring questions/cards to the substantive topic guides. > Density over completeness: the cram sheet distills, it doesn't re-teach. If it reads like a paragraph, > tighten it into cue → answer rows. --- ## 6b. Pharmacology data (`drugs[]`) — optional, powers the Pharmacology view A pack **may** include a top-level **`drugs[]`** array. It is **optional and additive** — leave it out and nothing changes; include it and the app's **Pharmacology** view builds a cross-week **drug index** from every *enabled* pack: it merges your records (and those from other packs) by a stable id, groups them by drug class, and shows the faceted fields with a link back to the week/guide each fact came from. This is content the learner reads alongside the topic guides — only add it when your source material actually covers the drug. **One record per drug, per pack:** ```json { "id": "rx:metformin", "name": "Metformin", "class": "rx:biguanide", "facets": { "use": "First-line type 2 diabetes", "mechanism": "↓ hepatic gluconeogenesis; ↑ peripheral glucose uptake", "adverse": "GI upset, B12 malabsorption; rare lactic acidosis", "contra": "eGFR < 30", "monitoring": "Renal function, B12" }, "ref": { "week": "Week 25 · Endocrine I", "topic": "Biguanide", "guide": "W25_02_Diabetes_Pharmacology.html" } } ``` | field | required | notes | |---|---|---| | `id` | yes | A **stable identifier**, `rx:`, where `` is the lowercase generic name, hyphenated — e.g. `rx:metformin`, `rx:atorvastatin`, `rx:piperacillin-tazobactam`. **Use the SAME id for the same drug in every pack** — that is exactly how the app merges, say, a statin mentioned in three weeks into ONE growing entry instead of three duplicates. Don't mint a new id for a drug that plausibly already has one. | | `name` | yes | Human-readable display name (e.g. `"Metformin"`). | | `class` | optional | A class id, `rx:` (e.g. `rx:statin`, `rx:ace-inhibitor`, `rx:sglt2-inhibitor`). The view groups drugs under their class heading. Use a consistent slug across packs; omit if no sensible class. | | `facets` | yes | An object holding **only the facets your source covers**, drawn from exactly these keys: `use`, `mechanism`, `dosing`, `contra` (cautions/contraindications), `adverse` (adverse effects), `monitoring`, `interactions`. Each value is a **short phrase, not prose** — it renders as a faceted line. Include 2–5 of them; never invent keys. | | `ref` | yes | `{ week, topic, guide }` locating the source so the view can link back. `week` = this pack's `weeks` string (or just the week label); `topic` = the topic/section; **`guide` MUST equal the `file` of a real `guides[]` entry** in this pack — the app deep-links to it. | **Rules of thumb:** - **Reuse ids; that's the whole point.** Consistent `rx:` ids across weeks are what let the index consolidate a drug; inconsistent ids produce duplicates. Pick the obvious generic-name slug. - **One record per drug per pack** — don't repeat the same drug twice in one pack's `drugs[]`. (Across *different* packs is expected and is what merges.) - **Short facet values.** Aim for the one high-yield phrase per facet, like the cram sheet's cue→answer density — not a paragraph. - **Point `ref.guide` at the guide that teaches the drug** (often a pharmacology or therapeutics guide). If you have no matching guide, you can still include the drug, but a valid `guide` file makes the back-link work. - **It's optional.** If the week isn't drug-heavy, skip `drugs[]` entirely — an empty or absent array is fine and never fails validation. --- ## 7. Validation checklist (every item must pass) **Pack:** JSON object with `id`, `pack`, `formatVersion`, `version`, `author`; `questions` and/or `cards` arrays; a `guides` array if any item carries a `guide`. **Each question:** `sys`, `topic`, `stem`; `options.length ≥ 2`; `correct` integer in `0…options.length-1`; **`difficulty` ∈ {easy, medium, hard}**. **Each card:** `sys`, `topic`, valid `type`; and by type — `mcq` (`prompt`, `options` ≥2, `correct` in range) · `multi` (`prompt`, `options`, `correct` = array of in-range indices) · `cloze` (`text` with ≥1 `{{…}}`) · `order` (`prompt`, `items` ≥2, in correct order) · `match` (`prompt`, `pairs` of 2-element arrays) · `qa` (`prompt`, `answer`). All non-`cloze` cards need a `prompt`. **Guides:** every `guide.f` used anywhere **resolves to a `guides[]` entry whose `file` matches**; every `guides[]` entry has non-empty `html`; **the LAST guide is the pack's cram sheet (§6a)**. **JSON hygiene:** 0-based `correct`; straight quotes; HTML inside strings must keep the JSON valid (escape inner double quotes, or use single quotes inside the HTML). **Parses cleanly (do this last):** the whole file is valid JSON with **no prose, code fences, or citation/grounding/footnote markers** anywhere (see §8). Run it through a strict JSON parser — if it doesn't parse, it won't import. **Substance & coverage:** **6–10 narrow topic guides for a dense one-week pack** (not a single sparse page), each with real sections/tables, **plus a cram sheet as the final guide (§6a)**; **most questions and cards carry a `guide` pointer**; counts meet the targets and are **scaled to the weeks covered** (10–20 questions — favour the upper end, 18–20, for a dense week — and 40–60 cards *per week*); difficulty lands near the **~30 / 55 / 15** easy/medium/hard spread, with **hard** items testing contraindications, emergencies, or multi-step reasoning (not just longer stems). **Options & card mix:** **no position-REFERENCING options** anywhere (`"A and B"`, `"both of the above"`, `"the first option"`) — options are shuffled at render (§2). ("All/None of the above" are fine — the app anchors them.) Card types are **varied, not cloze-heavy** (cloze ≲ 35% of the deck); **every `multi` card has ≥1 false option** (never all-correct, never "all-but-the-last"). **Placement filled:** `school` / `year` / (`term`) / `course` / `weeks` are present (ask if unknown, don't leave null), and **`course` is the grouping block shared across weeks (e.g. a course/block name), not the week's subject.** --- ## 7a. Build it programmatically and validate — don't hand-write the JSON **If you can execute code (a Python sandbox, code interpreter, notebook, etc.), build the pack with a script instead of typing JSON by hand.** Hand-authored JSON is where the import-breaking failures come from — and they are *silent*: the user drags in the file and nothing appears, with no error. The most common ones are mechanical and 100% catchable: - **Minified / single-line JSON** that's unreadable and hard to diff → fixed by pretty-printing. - **Citation / grounding / footnote markers your tooling injects** — `start_span`/`end_span`, `【…】`, ` ``` ` fences, `[1]`-style cites — **a single one makes the whole file fail to parse** (see §8). - **Broken `correct` indices, unbalanced `{{…}}` cloze blanks, a `guide.f` that matches no guide, a question with no `difficulty`** — each silently breaks or degrades the pack. The workflow that prevents all of the above: 1. **Assemble** the pack as a native data structure (lists/dicts), not a hand-typed string. 2. **Validate** it against the §7 checklist *and* scan for the §8 artifacts. 3. **Pretty-print** with 1- or 2-space indentation. 4. **Refuse to write/deliver** if validation fails — fix, then re-run. > A validator checks **structure, not substance.** It cannot tell you a guide is too thin or a question > is one shallow line — that's on the content instructions in §3 (volume) and §6 (substantive guides). > Treat the heuristic warnings below (guide length, explanation length, counts) as nudges, not a pass. ### Reference validator (Python — copy, adapt, run) ```python import json, re from collections import Counter CARD_TYPES = {"mcq", "multi", "cloze", "order", "match", "qa"} ARTIFACTS = ["start_span", "end_span", "【", "】", "```"] # any of these breaks the import # Options that REFERENCE specific other options break when the app shuffles. ("All/None of the above| # these" are NOT flagged — the app v0.2.63+ anchors them to their slot.) Conservative on purpose, so it # won't false-positive on legit answers like "Hepatitis A and B" or "Vitamin A and D". POSITIONAL = re.compile(r"\b(both of the above|neither of the above|both of these|" r"(option|answer)s? [a-e0-9]\b|" r"the (first|second|third|fourth|last) (option|answer|choice))", re.I) def validate_pack(pack): errs, warns = [], [] for k in ("pack", "id", "formatVersion", "version"): if not pack.get(k): errs.append(f"missing top-level field: {k}") qs, cs, gs = pack.get("questions", []), pack.get("cards", []), pack.get("guides", []) gfiles = {g.get("file") for g in gs} ids = [x.get("id") for x in qs + cs if x.get("id")] for i, n in Counter(ids).items(): if n > 1: errs.append(f"duplicate id: {i} (x{n})") for q in qs: qid = q.get("id", "?") if not all(q.get(k) for k in ("sys", "topic", "stem")): errs.append(f"{qid}: missing sys/topic/stem") opts = q.get("options", []) if len(opts) < 2 or not isinstance(q.get("correct"), int) or not (0 <= q.get("correct", -1) < len(opts)): errs.append(f"{qid}: bad options/correct") if q.get("difficulty") not in ("easy", "medium", "hard"): errs.append(f"{qid}: difficulty must be easy/medium/hard") if q.get("guide", {}).get("f") and q["guide"]["f"] not in gfiles: errs.append(f"{qid}: guide.f '{q['guide']['f']}' matches no guide") if len(q.get("explain", "")) < 80: warns.append(f"{qid}: explanation looks thin") for o in opts: if isinstance(o, str) and POSITIONAL.search(o): warns.append(f"{qid}: position-dependent option {o!r} — reword (options are shuffled)") for c in cs: cid, t = c.get("id", "?"), c.get("type") if t not in CARD_TYPES: errs.append(f"{cid}: bad card type {t!r}"); continue if "difficulty" in c: errs.append(f"{cid}: cards must NOT carry difficulty") if t in {"mcq", "multi", "order", "match", "qa"} and not c.get("prompt"): errs.append(f"{cid}: {t} needs a prompt") if t == "mcq" and not (0 <= c.get("correct", -1) < len(c.get("options", []))): errs.append(f"{cid}: bad mcq correct") if t == "multi" and not (isinstance(c.get("correct"), list) and all(0 <= i < len(c.get("options", [])) for i in c.get("correct", []))): errs.append(f"{cid}: bad multi correct") if t == "multi" and isinstance(c.get("correct"), list) and len(c["correct"]) >= len(c.get("options", [])): warns.append(f"{cid}: multi marks ALL options correct — add a false option") if t in {"mcq", "multi"}: for o in c.get("options", []): if isinstance(o, str) and POSITIONAL.search(o): warns.append(f"{cid}: position-dependent option {o!r} — reword (options are shuffled)") if t == "cloze": txt = c.get("text", "") if txt.count("{{") != txt.count("}}") or txt.count("{{") == 0: errs.append(f"{cid}: unbalanced/empty cloze blanks") if t == "qa" and not c.get("answer"): errs.append(f"{cid}: qa needs an answer") if t == "match" and (not c.get("pairs") or any(len(p) != 2 for p in c.get("pairs", []))): errs.append(f"{cid}: match pairs must be 2-element arrays") if c.get("guide", {}).get("f") and c["guide"]["f"] not in gfiles: errs.append(f"{cid}: guide.f '{c['guide']['f']}' matches no guide") for g in gs: if not g.get("html"): errs.append(f"guide {g.get('file')}: empty html") elif len(g["html"]) < 1500: warns.append(f"guide {g.get('file')}: looks thin (<1500 chars)") if gs and not any("cram" in (g.get("title","") or "").lower() for g in gs): warns.append("no cram-sheet guide — every pack should end with a one-page cram sheet (§6a)") blob = json.dumps(pack, ensure_ascii=False) hit = [m for m in ARTIFACTS if m in blob] if hit: errs.append(f"citation/markdown artifacts present: {hit}") types = Counter(c.get("type") for c in cs) if cs and types.get("cloze", 0) > 0.35 * len(cs): warns.append(f"cloze cards {types['cloze']}/{len(cs)} (>35%) — vary the card mix (more qa/mcq/order)") if len(gs) < 6: warns.append(f"only {len(gs)} guide(s) — a dense one-week pack usually wants ~6–10 narrow guides") diffs = Counter(q.get("difficulty") for q in qs) print(f"questions={len(qs)} cards={len(cs)} guides={len(gs)} " f"difficulty={dict(diffs)} cardtypes={dict(types)}") return errs, warns # usage: # errs, warns = validate_pack(pack) # for w in warns: print("warn:", w) # if errs: # for e in errs: print("ERROR:", e) # raise SystemExit("NOT WRITTEN — fix the errors above.") # with open(out_name, "w", encoding="utf-8") as f: # json.dump(pack, f, ensure_ascii=False, indent=1) # pretty-printed, never minified ``` **If you cannot run code,** you can't skip validation — you just do it by hand: re-read §7 item by item, then paste the finished text into a strict JSON parser (per §8) and confirm it parses *before* delivering. --- ## 8. Output instructions > **⚠ Output hygiene — the #1 cause of a pack that won't import.** The pack file must be **pure, > valid JSON and nothing else.** Before you deliver: > - **No prose, no explanations, and no Markdown code fences** inside the file — the file is JSON from > the first `{` to the last `}`. > - **Strip every citation / grounding / source / footnote marker your tooling may inject** — e.g. > bracketed span tags like `[span_0](start_span)…[span_0](end_span)`, `【…】`, superscript reference > numbers, or `[1]`-style cites. **A single stray marker anywhere makes `JSON.parse` reject the > entire file**, so the user sees nothing import. > - **Parse-test the final text with a strict JSON parser** (it either parses cleanly or it doesn't). > Also re-run the §7 checklist. Do not hand over a pack you have not verified parses. **If you can run > code, do all of this with the §7a validator rather than by eye — it catches every artifact above.** When you finish, produce **one downloadable file** (not just code in chat): 1. The **pack `.json`**, **with the topic guides embedded** in `guides[]`. This single file is the complete deliverable — the embedded guides make it fully self-sufficient (Topic Guides reader included). **Name the file to mirror the pack's placement (§2)** so the learner's packs stay organized and sort sensibly in a folder: **`__Week__v.json`** — e.g. `Year1_CPC1_Week09_Pediatrics_v2.0.json`, or `Year1_Cardiology_Week12_Arrhythmias_v1.0.json`. Drop any level the learner doesn't use (a single-week pack with no course is just `Week12_Cardiology_v1.0.json`), and use the same week number(s) as the `weeks` field so name and metadata agree. The filename is for the learner's convenience only — inside the app, packs are identified by `id` and sorted by their `school`/`year`/`course`/`weeks` fields, not the filename. 2. A short report in chat: how many questions (and the easy/medium/hard split), how many cards, and which guides are embedded. Do **not** emit standalone guide `.html` files unless the user asks for printable copies. --- ## 9. How the human uses the output (for your closing summary) 1. Open the app at **https://studysuite.app** (nothing to install; a local copy of the app `.html` works identically). 2. Drag the new `.json` pack onto the drop zone — it persists and appears in the **Content library**, toggleable on/off. (The site also offers the author's default packs with one-click "+ Add to library".) 3. Pick a **Session difficulty** — Easy/Medium/Hard are multi-select toggles, "All" selects all three — for Practice and Exam; **Review** ignores difficulty. Open **Topic Guides** to read the bundled guides. 4. **Backup all** periodically — one file with packs, progress, and settings, restorable anywhere. Load multiple weeks and toggle to whatever's being studied. Add weeks anytime by generating more packs with this guide. Bump each pack's `version`/`updated` when you revise it.