Skip to content

Lecture ​

Lecture explains code the way a lecturer at a chalkboard would – plain language, one idea at a time, a diagram when the shape is the point. Point it at a file or a whole system and it writes a self-contained HTML slide deck with drawn D2 diagrams, pitched at a beginner reading the code cold. Or the session itself can flip into a live interactive lecturer that teaches, quizzes, and marks the code you write. It's the companion to finn-style: finn-style is how the code looks, lecture is how it gets explained.

Formerly chalk

This module used to be called chalk. Same skill, same commands, renamed only.

Slides only since amendment 32

Lecture used to write a Markdown .lecture.md doc as well, and drew its diagrams in Mermaid through a headless Chrome. Both halves retired together on 2026-07-29 – Finn only ever read the decks, and the Mermaid path failed outright on a machine without Chrome. The .slides.md is now source and the HTML is the deliverable. The frozen copy of the module with both halves intact is harness/retired/chalk-lecture+slides/, named for the module's old identity since it predates the rename.

In Practice ​

Explain a file or a system. You want code documented for someone who has never seen it:

/lecture path/to/file_or_system

It reads enough to explain the whole thing, writes <name>.slides.md into a lectures/ folder at the working directory root, renders it to HTML beside it, and never touches the source.

An example outcome. Point it at a lock-free job system and you get lectures/job_system.slides.html – a deck that opens with an analogy, draws the structure, and explains each tricky line one slide at a time. Open it in a browser and page through with the arrows, space, or a scroll of the wheel; the diagrams are drawn for real rather than shown as raw source.

Teach live instead of writing a deck. When you'd rather be tutored than handed an artifact:

/lecturer

This flips the session into lecturer mode. Instead of dumping full code it hands you the smallest snippet that carries the idea, checks each concept landed before stacking the next, drops the odd quiz, and marks the code you write. It holds every turn until you say /lecturer off.

Keep one deck per thing. /lecture-index regenerates LECTURES.md, a table of every deck with its subject and a one-line gist, so the next pass links an existing deck instead of re-explaining code already covered.

Diagrams, and the Diagram Toolkit ​

Diagrams are written as plain D2 in ```d2 fenced blocks. The renderer pulls each one out and hands it to the diagram toolkit, which draws it offline – no browser, no network. Lecture prepends its own palette prelude to every block, so a deck author writes plain D2 and gets the lecture look without setting a single colour.

The toolkit is a soft dependency (wants, not needs). With the diagram part installed the blocks are drawn; without it they stay as source in the deck and the render still succeeds, saying so up front. A project that only wants lecture is never forced to pull a D2 and resvg payload it will not use.

A D2 gotcha worth knowing

Never put a vars: { d2-config: ... } block in a lecture diagram. Lecture's palette prelude uses ** style globs, and a glob recurses into vars and tries to style d2-config itself, so the source stops compiling – with an error that names the glob line rather than the vars block. Padding rides a D2_PAD env var instead; theming is the renderer's job anyway.

Output Formats ​

Lecture is HTML only by its own hand. A PDF is a manual escape hatch you reach for only by running /lecture-pdf yourself.

FormatHow it's madeWhen
HTMLrender-slides.nu with no --format, the default everywhereThe deck lecture makes on its own – a self-contained interactive file, no browser needed to build it
PDF/lecture-pdf, which passes --format pdf to MarpManual only, when you want a portable printable deck to hand round or archive

The HTML path needs no browser at all. Chrome is required only for the PDF, because Marp drives one itself, and that path says so clearly when it can't find one. Both formats wear the same look – a dark background with medium and darker green accents, the diagrams themed to match.

Skill and References ​

SKILL.md ​

The procedure – read the target, find the one-sentence big picture, plan the diagrams, write the deck, save it as <name>.slides.md, render it, never edit the source. It also routes to lecturer mode and to the lecture index so it links an existing deck rather than re-explaining the same code.

slides.md ​

The shape of a deck and how to write one – the teaching spine (title and hook, a big picture with an analogy, a structure map, the piece-by-piece walkthrough, a runtime flow, why it's built this way, a recap, an optional have-a-go), one idea per slide, how to group the short pieces so you don't get a run of near-empty slides, and the Marp-flavoured .slides.md shape the renderer expects.

d2-cheatsheet.md ​

Which diagram for which job – a flow for control flow, shape: sequence_diagram for call order, shape: class for structure, plain nodes and arrows for a state machine, a map for dependency wiring, and nesting for containment. Every snippet in it is compile-tested.

voice.md ​

How it should read – the finn-style prose voice pitched down for a beginner: define every term the first time, one idea at a time, concrete analogies, and name each finn-style convention (the m_ prefix, the two-phase class layout, CASTTO) as it comes up.

lecturer-mode.md ​

The live teaching contract – snippets not full code, speak plainly, check they get it, quiz now and then, mark their code, and hold all of it every turn until it's dropped.

Commands ​

lecture.md ​

/lecture – writes and renders a deck for a file or system end to end, then tells you where the HTML landed.

lecture-pdf.md ​

/lecture-pdf – the one place a PDF gets built, the manual escape hatch, off limits everywhere else, and the only path that needs Chrome.

lecturer.md ​

/lecturer – flips the session into lecturer mode; /lecturer off drops it.

lecture-index.md ​

/lecture-index – regenerates LECTURES.md from the lectures/ folder, on demand, never wired to a hook.

Scripts ​

render-slides.nu ​

The renderer – pulls every D2 block out, hands each to the diagram toolkit to draw offline, then builds the self-contained HTML deck (and the Marp PDF when asked). It resolves the toolkit beside itself, with LECTURE_DIAGRAM_RENDER as an override, and falls back to leaving the D2 as source when there is none. It also carries the finn-style C++ syntax highlighter baked into the HTML template.

lecture-index.nu ​

The corpus indexer – scans a directory for *.slides.md and writes LECTURES.md, each row carrying a deck's subject and a one-line gist, with a wiki column stubbed for later cross-linking. It strips Marp front matter and HTML speaker-note comments first, so neither lands in the gist column.

lecture-dark.css ​

The Marp theme – the dark background with green accents the PDF wears. The deck's diagram palette is a D2 prelude in render-slides.nu rather than a theme file.

Agent ​

lecturer.md ​

The lecturer persona – a subagent for a longer guided walkthrough, deferring entirely to the lecture skill and its references as the single source of truth.

Connects to ​

  • Wants diagram – a soft dependency, the toolkit draws the deck's D2 blocks offline when it's installed, and the deck still builds without it.
  • Reused by find-todos – its render-todos.nu borrows lecture's marked-to-HTML pipeline and a trimmed copy of the lecture dark green theme to render TODOS.md into a matching self-contained page.
  • Stubbed for wiki – LECTURES.md carries an empty wiki column, reserved for cross-linking decks into the generated wiki when that work lands. Note that this page's own diagram above is Mermaid, not D2: VitePress renders Mermaid client-side, which is exactly why the wiki needed no diagram-toolkit edge of its own.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/lecture/USAGE.md – that one is the thin command, config, and gotcha reference, this page is the fuller depth of the same module.