Krog - The Complete User Manual & Authoring Guide

1. Introduction & Manifesto

About the Author (Dany)

Hi, I'm Dany. I'm a software engineer currently studying Medicine at the University of El Salvador. Like many students who discovered modern generative AI, I initially threw it at every problem: summarizing clinical textbooks, formatting outlines, and churning out multiple-choice flashcards. But very quickly, a troubling pattern emerged. The tools were undeniably capable, but they were doing the actual thinking for me. Instead of scaffolding my intellectual synthesis, they turned studying into a passive, click-and-skim habit.

Learning requires cognitive friction. In medical physiology, pathology, or systems software engineering, true comprehension is forged when you wrestle with ambiguity, test hypotheses, and confront your own gaps. When software presents a pre-cooked, uneditable summary, it robs you of that synthesis.

Consider NotebookLM: while an impressive technological feat, it operates as a paternalistic black box. You can ask for adjustments, but the underlying system prompt is concealed, the processing logic is proprietary, and the generated documents are treated as immutable artifacts. You cannot click directly into an AI briefing doc to strike through an ambiguous sentence, correct a subtle diagnostic inaccuracy, or reformat an anatomical distinction in your own words.

I built Krog to break that paradigm. Krog is an open, sovereign Learning Management System designed to return complete control of the study process back to the learner. Every prompt is transparent; every generated question is editable; every asset can be stored, exported, and run on the user's terms—whether through cloud APIs or local models running offline on your own machine.

What Krog Is (and What It Is Not)

• Krog IS: An environment for active recall, modular content authoring, structured evaluation, real-time peer learning, and rigorous institutional assessments.
• Krog IS NOT: An opaque wrapper around a closed API that locks your knowledge behind paywalls and proprietary formats.

Core Architectural Primitives

The Krog ecosystem is built upon six interconnected primitives:

1. Contents (Content): Long-form markdown notes, uploaded PDF references, document extracts, and web resources.
2. Drawings (Drawing): Vector whiteboard diagrams, visual mind maps, and anatomical sketches.
3. Questions (Question): Atomic active-recall items adhering to a strict, portable schema.
4. Exams (Exam): Cohesive suites of questions paired with optional study material, time parameters, and access controls.
5. Collections (Collection): Curated paths grouping multiple exams and study materials into semester-long curricula.
6. Organizations (Organization): Multi-tenant institutional hubs featuring teams, shared vaults, and granular permissions.

2. Account, Personalization & Visual Flavors

Profile & Identity

Every user on Krog has a unique handle (username), full name, bio, and customizable avatar.

• Public Visibility Toggle: You can independently choose whether your profile, social activity, and study statistics are public or restricted strictly to your organization and followers (profile_picture_public, social_public).
• Study Streaks & Milestones: Daily consistency is tracked via streak and longestStreak. Completing a daily retrieval drill or reading assignment maintains the streak counter.
• Badges: Performance achievements unlock profile badges.

The Flavor System: 50+ Curated Typographic Themes

Visual fatigue during long study sessions contributes heavily to cognitive burnout. Krog features an extensive theme engine known as Design Flavors. Rather than generic dark/light modes, Flavors alter palette variables, contrast ratios, border radiuses, and typographic rendering:

• Minimalist & Paper: minimal, notebook, legalpad, chalkboard, typewriter, eink, newspaper.
• Technical & Dark: krog (signature emerald-dark), nord, dracula, cyberpunk, terminal, developer, repository, charcoal, onyx.
• Artistic & Warm: swiss, bauhaus, midcentury, sakura, warmcream, coffee, desert, sumi, kyoto.
• Focus & High Contrast: studyfocus, highcontrast, scientific, blueprint, wireframe.

Users can also independently customize the App Font (UI controls) and the Material Font (long-form reading serif, such as Literata or Merriweather).

3. The Authoring Engine: Writing Study Material in Krog

Writing study material in Krog is built on the concept of the Executable Textbook. Rather than producing static, passive text, Krog's Markdown engine empowers authors to construct dynamic, interactive pedagogical documents using plain text directives, structured semantic containers, and embedded active-recall widgets.

Every section below showcases its feature using interactive "Text" and "Result" tabs so you can inspect the exact authoring markup and immediately see how Krog renders it.

1. Chapter Boundaries (------)

Study material can be split into navigable chapters by inserting six dashes on their own line:

Copy code
# Chapter 1: Foundations of Neurotransmission
Content for chapter 1...

------

# Chapter 2: Synaptic Plasticity & Long-Term Potentiation
Content for chapter 2...

Krog parses each chapter into an interactive reading view with a sidebar table of contents, reading time estimates, and per-chapter completion checkboxes (StudyProgress). Flow directives declared in preceding chapters automatically carry forward across boundaries.

2. Flow Directives Reference

Flow directives begin with @ at the start of a line. They modify document layout and typography dynamically from that point downward until changed again or reset:

To reset any directive to its default, pass default, off, or none (e.g. @align default, @columns off).

3. Inline Enhancements: Colors, Highlights & Typography

Copy code
* **Scoped Fonts**: <font jbmono>Monospaced code snippet</font> and <font cmu>Mathematical CMU Serif</font>.
* **Size Spans**: <size 20>Prominent note text</size>.
* **Color Tags**: <c emerald>Emerald highlight</c> and <c rose>Rose critical text</c>.
* **Fluorescent Highlights**: ==High-yield concept== and =={sky}:Sky-tinted phrase==.
* **Arrow Auto-Formatting**: Resting state → Depolarization ⇒ Action potential threshold.

4. Active Recall: Cloze Deletions, Spoilers & Speech

Click-to-Reveal Cloze Deletions

Wrap words in double curly braces to hide them behind an interactive clickable pill:

Copy code
The action potential in ventricular myocytes begins with Phase 0, driven by the rapid opening of {{voltage-gated fast Na+ channels}}.

Interactive Spoiler Blocks (<spoiler>)

Hide full diagnostic solutions or rationales until clicked:

Copy code
What is the antidote for acetaminophen toxicity?
<spoiler>
**N-acetylcysteine (NAC)**, which replenishes hepatic glutathione stores.
</spoiler>

Text-to-Speech Pronunciation (<play>)

Clicking the word speaks it out loud using the browser's speech synthesis engine:

Copy code
Verify medical terminology: <play lang="es">esternocleidomastoideo</play> and French anatomy: <play lang="fr">trompe-l'œil</play>.

5. Semantic Container Callouts

Wrap contextual notes inside semantic XML tags. Unclosed tags safely auto-close at the next heading:

Copy code
<tip>
**Mnemonic for Essential Amino Acids:** PVT TIM HaLL
(Phenylalanine, Valine, Threonine, Tryptophan, Isoleucine, Methionine, Histidine, Leucine, Lysine).
</tip>

<warning>
Beta-blockers without intrinsic sympathomimetic activity are strictly contraindicated in acute decompensated heart failure with pulmonary edema.
</warning>

<key>
The primary hemodynamic hallmark of severe aortic stenosis is a systolic ejection pressure gradient between the left ventricle and the aorta.
</key>

6. Academic & Scientific Numbered Boxes

For formal STEM curricula, Krog features numbered theorem environments with automatic CSS counter numbering:

Copy code
<theorem Central Limit Theorem>
Let $X_1, X_2, \dots, X_n$ be independent and identically distributed random variables with $\mathbb{E}[X_i] = \mu$ and $\operatorname{Var}(X_i) = \sigma^2 < \infty$. 
As $n \to \infty$, the sample mean $\bar{X}_n$ converges in distribution to a normal distribution:
$$\sqrt{n}\left(\bar{X}_n - \mu\right) \xrightarrow{d} \mathcal{N}(0, \sigma^2)$$
</theorem>

<example Clinical Vignette>
A 62-year-old male with sudden onset retrosternal crushing chest pain radiating to the left jaw. Troponin I is elevated at 4.2 ng/mL. The most urgent next step is activating the cardiac catheterization team for primary percutaneous coronary intervention (PCI).
</example>

7. Step-by-Step Clinical & Procedural Workflows (<steps>)

Format sequential clinical workflows or engineering algorithms with high-visibility numbered step badges:

Copy code
<steps>
1. **Initial Assessment**: Verify airway patency, breathing stability, and circulation (ABCs).
2. **Access & Labs**: Establish two large-bore peripheral IVs; draw type and screen.
3. **Fluid Resuscitation**: Administer weight-based crystalloid bolus (30 mL/kg).
4. **Re-evaluation**: Assess mean arterial pressure (MAP) and hourly urine output response.
</steps>

8. Architectural & Clinical Process Diagrams (<mermaid>)

Krog natively compiles Mermaid diagrams via fenced code blocks or the <mermaid> tag:

Copy code
<mermaid>
graph TD
    A[Patient with Acute Chest Pain] --> B{ECG Findings}
    B -->|ST Elevation| C[STEMI: Immediate Catheterization Lab]
    B -->|Normal / Inconclusive| D[Serial Troponins & Monitoring]
    D -->|Elevated Troponin| E[NSTEMI Protocol]
    D -->|Negative Troponins| F[Outpatient Provocative Testing]
</mermaid>

9. Embedded Interactive Questions & Flip Cards

Embed fully interactive retrieval practice directly within the study guide:

Copy code
<question>
<title>What is the primary neurotransmitter at the neuromuscular junction?</title>
<option>Norepinephrine</option>
<option correct>Acetylcholine</option>
<option>Dopamine</option>
<option>Glutamate</option>
<explanation>
Somatic motor neurons release acetylcholine (ACh) onto nicotinic cholinergic receptors at the motor end plate.
</explanation>
</question>

<flashcard>
<front>What is Starling's Law of the Heart?</front>
<back>Stroke volume of the heart increases in response to an increase in end-diastolic volume (preload), which stretches myocardial fibers.</back>
</flashcard>

10. Comparative Layouts: Tabs & Columns

Side-by-Side Comparison (<compare>)

Copy code
<compare>
<col title="Crohn's Disease">
- Transmural inflammation
- Skip lesions ("cobblestoning")
- Non-caseating granulomas
- Terminal ileum most common site
</col>
<col title="Ulcerative Colitis">
- Mucosal/submucosal involvement
- Continuous ascending lesions from rectum
- Crypt abscesses & pseudopolyps
- Limited to the large colon
</col>
</compare>

11. Scientific, Chemical & Interactive Sandbox Elements

2D/3D Chemical Molecule (<mol>)

Pass a valid SMILES string to render an interactive chemical structure:

Copy code
<mol>CC(=O)OC1=CC=CC=C1C(=O)O</mol>

Mathematical Function Plotting (<plot>)

Plot curves dynamically without static screenshots:

Copy code
<plot domain="-10..10" range="-2..2" title="Sinusoidal Waveform">
sin(x)
</plot>

Sequential Timelines (<timeline>)

Copy code
<timeline>
Week 3 :: Gastrulation begins; trilaminar embryonic disc forms.
Week 4 :: Neural tube closure completes; cardiac tube initiates contractions.
Week 8 :: Organogenesis completes; embryonic period transitions to fetal stage.
</timeline>

Live Interactive Code Sandbox (<code-sandbox>)

Copy code
<code-sandbox>
<slider var="voltage" min="1" max="24" step="1">12</slider>
<cell type="js">
return `Power dissipated across a 4Ω resistor: ${(voltage ** 2) / 4} Watts`;
</cell>
</code-sandbox>

12. Advanced Tables & Media Embeds

All Markdown tables in Krog automatically feature hover controls to inspect them in a full-screen dialog or download a PNG image (table.png):

Copy code
| Parameter | Normal Range | Clinical Significance |
| :--- | :--- | :--- |
| Serum Potassium ($K^+$) | 3.5 – 5.0 mEq/L | Cardiac arrhythmias upon deviation |
| Serum Sodium ($Na^+$) | 135 – 145 mEq/L | Extracellular osmolality & volume |
| Serum Calcium ($Ca^{2+}$) | 8.5 – 10.5 mg/dL | Neuromuscular excitability |

4. Visual Synthesis: Diagrams & Canvas Drawings

Medicine, architecture, and computer systems cannot be understood through text alone. Krog integrates a full vector whiteboard engine directly into the study workspace (Drawing).

Whiteboard Capabilities

• Infinite Vector Canvas: Freehand sketching, arrows, geometric containers, text cards, and embedded image assets.
• Bi-directional Linking: Link a diagram canvas directly into an Exam or Study Material chapter.
• Collaborative Editing: Add teammates as editors (editors: String[]) to co-sketch anatomical diagrams, network topologies, or workflow charts in real time.

5. The Question Engine: Anatomy & Compiler Syntax

The Plain-Text Question Compiler Syntax

Krog's hallmark feature is its universal question format. You do not need to click through ten nested web forms to create a quiz. You write or paste formatted plain-text blocks:

Copy code
q:{Short question title or prompt}
d:{Optional body context, clinical vignette, syntax, or Markdown}
o:{Option 1}{Option 2}{Option 3}{Option 4}
co:{Exact text of the correct option}
e:{Detailed explanation with Markdown and LaTeX}

Parsing Rules:

• q: The primary inquiry. Must be concise and unambiguous.
• d: Contextual background. Supports full Markdown, code snippets, tables, and images.
• o: Enclosed within {braces}. Minimum of two options.
• co: Must match the verbatim text inside one of the {options}.
• e: Rich pedagogical feedback explaining both why the correct answer holds and why each alternative is invalid.

The Four Question Archetypes

1. Single Choice (single)

Copy code
q:Action potential phase 0 in ventricular myocytes
d:Which ion channel carries the rapid inward current responsible for Phase 0 depolarization?
o:{Voltage-gated L-type Ca2+ channels}{Voltage-gated fast Na+ channels}{Inward rectifier K+ channels}{Transient outward K+ channels}
co:Voltage-gated fast Na+ channels
e:Phase 0 upstroke in ventricular myocytes is mediated by the rapid influx of Na+ through fast voltage-gated Na+ channels (Nav1.5).

2. Multiple Choice (multi)

Copy code
q:Features of Diabetic Ketoacidosis (DKA)
d:Select all laboratory findings characteristic of unmanaged acute DKA:
o:{Metabolic acidosis with elevated anion gap}{Serum bicarbonate > 24 mEq/L}{Ketonuria}{Hyperglycemia (> 250 mg/dL)}
co:Metabolic acidosis with elevated anion gap
co:Ketonuria
co:Hyperglycemia (> 250 mg/dL)
e:DKA is marked by high anion gap metabolic acidosis, elevated blood glucose, and ketonemia/ketonuria. Bicarbonate is characteristically reduced (< 18 mEq/L).

3. Direct Write (write)

Copy code
q:Pathognomonic sign of measles
d:Small, irregular red spots with bluish-white centers found on the buccal mucosa opposite the molars:
co:Koplik spots
e:Koplik spots appear 24-48 hours before the generalized maculopapular exanthem of measles.

4. Relational Match (match)

Copy code
q:Pair the cranial nerve with its corresponding exit foramen:
o:{CN II (Optic)}{CN V2 (Maxillary)}{CN V3 (Mandibular)}{CN VII (Facial)}
m:{Optic canal}{Foramen rotundum}{Foramen ovale}{Internal acoustic meatus}
p:{CN II (Optic) -> Optic canal}{CN V2 (Maxillary) -> Foramen rotundum}{CN V3 (Mandibular) -> Foramen ovale}{CN VII (Facial) -> Internal acoustic meatus}
e:CN II exits through the optic canal; CN V branches through superior orbital fissure (V1), foramen rotundum (V2), and foramen ovale (V3); CN VII enters the internal acoustic meatus.

6. Study Modes: Individual Mastery & Retrieval Practice

1. Flashcard Mode

• Cards render the question prompt and body context.
• Clicking or pressing Space flips the card to reveal correct answers and explanations.
• Confidence keys (1: Again, 2: Hard, 3: Good, 4: Easy) register your retention status and update spaced repetition intervals.

2. Practice Drills & Diagnostics

When concluding a self-paced study session, Krog records an ExamAttempt detailing:

• Per-question scoring (questionResults: { questionId, score }).
• Time taken per item (duration).
• AI-driven performance breakdown (ExamAnalysis): identifies underlying conceptual weaknesses.

3. Integrated Study Timers

Under TimerCountdown, users can launch and save custom focus timers (Pomodoro, 50/10 intervals, or exam-length blocks) embedded in the navigation bar.

7. Institutional & Controlled Assessments

For universities, academies, and professional certifications, Krog provides an enterprise-ready examination environment.

Configuration Parameters

1. Restricted Access (allowedEmails): Add specific student emails. Unlisted accounts cannot launch the exam even if they hold the direct URL.
2. Password Gate (password): Set a proctored room code that students must enter synchronously in class.
3. Availability Windows (startDate & endDate): Exams automatically unlock and seal at specified ISO timestamps.
4. Time Limits (examDuration): Countdown timers force an automatic submission when time expires.
5. Linear Non-Backtracking Mode (allowGoBack: false): Students answer questions strictly in sequence. Once submitted, answers cannot be retroactively viewed or altered.
6. Attempt Caps (maxAttempts): Restrict students to a single official submission.
7. Grade Reveal Policies (viewGradeBehavior):
   • IMMEDIATELY: Instant score and feedback upon completion.
   • AFTER_END_DATE: Withholds answers until the formal window closes, preventing answer leaks.
   • OWNER_DECIDES: Withholds scores until the instructor manually reviews and releases them.

8. Curated Curricula: Collections & Learning Paths

Exams and materials can be compiled into structured multi-week syllabi called Collections (Collection).

• Linear Curriculum: Arrange modules sequentially (e.g., "Cardiology Week 1 -> Week 2 -> Clinical Practicum").
• Progress Tracking: Students save collections to their personal /my-learning dashboard, tracking cumulative completion.
• Curator Attribution: Authors retain full credit, while organizations can present branded course collections.

9. Organizations, Teams & Multi-User Governance

Organizations (/organization/:slug) enable institutions to manage departments, cohorts, and shared academic libraries.

Hierarchy & Membership

• Owner: Billing owner, organization deletion, transfer authority.
• Admins: Manage member invitations, create teams, configure organization-wide settings, and assign exam permissions.
• Members: Access organization vaults, participate in private exams, and join teams.

Team-Based Access & Granular Permissions

Rather than managing rights per student, administrators create Teams (e.g., "Class of 2027", "Neurology Faculty"). Permissions are assigned per asset:

• read: Take exams and review study materials without editing privileges.
• write: Add, modify, or delete questions and materials within the folder or exam.

10. Multiplayer Live Sessions ("Arena")

Krog includes a real-time multiplayer engine for classrooms, conferences, and study groups.

Hosting an Arena Game

1. Open any Exam and select Launch Multiplayer Arena.
2. A unique 6-character room code and QR code are displayed on the host screen.
3. Students join on mobile devices or laptops via /play.

Mechanics

• Synchronous Question Pacing: The host controls when questions begin and end.
• Speed & Accuracy Scoring: Points are calculated based on both correctness and rapid response times.
• Real-Time Leaderboard: Live animations display podium standings between questions.
• Review Breaks: The host screen displays choice distributions, allowing the instructor to explain misconceptions before proceeding.

11. AI Workflows & Independent Compute Playbooks

Krog empowers learners by maintaining absolute transparency over prompts and parser mechanics. You do not need to buy platform credits to process material.

Prompt Template for External Models

Copy and paste this prompt into Claude, ChatGPT, Gemini, or a local model (via Ollama) along with your text or notes:

Copy code
You are an expert pedagogical designer. Extract the key concepts from the text below and format them as a rigorous Krog-compatible question deck.

Follow this exact plain-text syntax for each question:
q:{Concise question title}
d:{Body, scenario, or context}
o:{Option 1}{Option 2}{Option 3}{Option 4}
co:{Verbatim text of the correct choice}
e:{Detailed pedagogical explanation of why this choice is correct and others are wrong}

Rules:
1. Wrap all choices in individual braces {}.
2. Ensure 'co' matches one of the options character-for-character.
3. Include high-yield conceptual distractors.
4. Output raw text only, ready for compilation.

Paste the output directly into Krog's Import Questions modal. Krog parses and renders the deck instantly into your personal library.

12. Community, Social Learning & Marketplace

Social Discoverability

• Explore Feed: Browse high-yield public decks curated by global peers and medical/technical educators.
• Collaborative Co-Authoring: Add co-editors to your exams (editors: String[]). Changes sync across authors with full notification history.
• Discussion Threads: Every question includes a collaborative comment thread (ExamComment), allowing learners to debate rationale, suggest alternative mnemonics, or report ambiguities.

Marketplace & Premium Decks

Educators and professional content creators can mark decks forSale: true and specify a price. Students purchase secure access via integrated checkout, supporting sovereign educational creators.

13. Appendix: Technical Reference & Schema Map

Database Reference Cheat Sheet

• Exam: The primary evaluation unit containing questions, access rules, and study materials.
• Content: Central markdown and document library.
• Drawing: Vector graphics and visual whiteboard records.
• ExamAttempt: Immutable record of a user's test session and individual scores.
• Organization: Institutional workspace with slug-based routing and role definitions.

Keyboard Shortcuts

• Space: Flip flashcard / Advance slide.
• 1, 2, 3, 4: Select multiple choice option / Rate card difficulty.
• Cmd/Ctrl + Enter: Submit written answer or compile question block.
• Esc: Close study conversation drawer or exit full-screen mode.

Krog is designed to respect your intelligence, your time, and your intellectual sovereignty. Happy studying!