Where v1 Fell Short
Lolevel v1 taught memory addresses, pointers, and registers through examples I built myself: a 16-cell memory grid, a pointer chain with a NULL scenario, a register allocator computing (x + y) * z. These were useful for a first pass, but they were synthetic; built to illustrate a concept, not drawn from a real, audited codebase.
The gap became obvious once I started reading xv6-riscv properly, working through entry.S, swtch.S, and vm.c via gittype, and typing through comparable code in typesec's typing mechanic. A tool meant to build intuition for computer architecture and OS internals should be teaching against a real system, not invented snippets standing in for one.
The current Lolevel draft still runs, but I'm not extending it. I'm rebuilding around xv6 instead.
The New Shape: Merge Two Existing Mechanics
I already have two mechanics working elsewhere. Typesec has you type real code, then tells you what you just typed. Mathemphetamine is quiz-based, with scoring and progression. Lolevel v2 points both mechanics at the same subject: xv6-riscv, MIT's teaching operating system.
Two sources anchor everything: MIT's xv6 book (rev5, RISC-V edition) and the xv6-riscv source repository itself. Every snippet and every quiz question has to trace back to one of these two, not to a paraphrased memory of how kernels generally work. xv6 itself has moved between architectures and revisions over the years, so details shift; grounding content in the actual current source is non-negotiable this time.
Planned Modules
Typing drills, RISC-V first: real snippets from entry.S, trampoline.S, swtch.S, kalloc.c, and vm.c. Type the code, then get told what it does and which kernel subsystem it belongs to.
A second typing track for AArch64 and x86-64, so the same constructs (syscall entry, stack frame setup, context switch) can be typed and compared across three instruction sets instead of just RISC-V. This is secondary; it comes after the RISC-V track is solid.
A quiz track covering OS fundamentals: processes, scheduling, virtual memory, traps and interrupts, the file system, locking. A separate quiz track for computer architecture proper: pipelining, caches, memory hierarchy, ISA design tradeoffs. Both reuse mathemphetamine's existing scoring and progression.
Build Approach
The full xv6 codebase is too much to cover in one pass, so this is going subsystem by subsystem. First slice: boot and the entry point, since everything downstream depends on it. Typing drills and quizzes for that one subsystem, built completely, before anything else.
Every subsystem not yet built (trap handling, virtual memory, scheduling, the file system, locking) shows up in the UI as a locked "coming soon" card from day one. The intended scope stays visible even while most of it is unbuilt.
Visual Rework
v1 was dark themed. v2 moves to a light theme with orange tints, closer to Apple Notes. Part aesthetic preference, part practical: the content is denser now (real assembly and C, not toy examples), and a lighter, calmer surface reads better across long sessions of typing and reading disassembly.
What Carries Over From v1
Two things I learned building v1 are shaping every decision in v2.
Interactivity has to be load-bearing, not decorative. In v1, tracing the double-pointer chain myself, rather than reading a diagram of one, was the moment the concept actually landed. v2 keeps that principle and raises the stakes: instead of a synthetic pointer chain, you're typing the actual swtch.S context switch and getting told what each instruction does to the real xv6 process struct.
The dependency order between concepts belongs in the product, not in a note telling you what order to read things. v1 locked modules in sequence because register allocation doesn't make sense before you understand addresses. v2 applies the same logic at the subsystem level: boot and entry point first, because trap handling and scheduling both assume you already understand how the kernel gets from the reset vector to running code.
Where This Is Going
I've written a build spec for phase one (the boot and entry point module, sourced directly from the book and the repo) and handed it to Claude Code, reusing typesec and mathemphetamine's existing stack so the three projects stay consistent. I'll write about the boot module specifically once it's working. This post is the record of why the direction changed and what the full scope is meant to look like once it's built out.