Writing the notes

The notes are the lesson's chapter in a book: they explain the concept properly, as a good technical book would, and tie it to the example the learner has just run. The read-along explains the code; the notes explain the idea, pointing into the code to make it concrete.

Write in the course language (language in .codelabgen/config.yaml). There is no length limit: the chapter is as long as the idea needs, and not a sentence longer. No filler, no marketing tone, no "in this lesson we will…" padding.

Structure

Adapt to the topic. A typical chapter:

1. The problem. What situation calls for this concept? What goes wrong without it? Start from something the learner already knows.
2. The concept. Define it precisely. Introduce terms one at a time, each defined on first use. Give the mental model that makes the rest follow.
3. How it works. The mechanism, with a diagram where structure or flow matters.
4. In our example. Map the concept onto the lesson code: which part does what, with snippets of the key parts, and a link to the read-along for the code walkthrough.
5. Run it. The real output of the program and what to notice in it (see "Real output").
6. Details and edge cases. Behaviour that surprises people, limits, interactions with what earlier lessons covered.
7. Common mistakes. As callouts, ideally from real pitfalls (the pitfalls source digests, issue trackers, the spec's experiments).
8. Experiments. What to try with the code (see "Experiments").
9. Summary. 3–6 bullets the learner should remember.
10. Self-check. 3–5 questions with answers hidden in <details>.
11. Further reading. Sources actually used, with links.

Accuracy

• Every claim about the technology must hold for the pinned version. Check against the official docs (WebFetch) and the installed sources (where they are: the runtime's reference in ${CLAUDE_PLUGIN_ROOT}/skills/code-authoring/references/). Use the concepts and pitfalls source digests in .codelabgen/sources/ when they exist.
• Read .codelabgen/research/deprecations.md if it exists, and never present a deprecated API as current.
• When unsure, say less or verify, rather than guess.
• Write in your own words. Never copy text from sources. Short quotes are fine when attributed.

Tying notes to the code

• Use snippet markers to show the key parts. codelabgen snippets sync fills them, exactly as in the read-along:

  <!-- snippet: src/l1_2_routing/graph.py#build_graph -->
  <!-- /snippet -->

• Link to the walkthrough with [разбор кода](readalong.md#…) and to files with relative links such as [graph.py](../src/l1_2_routing/graph.py).
• Refer to code by identifiers, never by line numbers.

Real output

Quote the live run's real output from the latest passing verify run: .codelabgen/runs/<id>/<latest>/live-run.log (the part after the command header). Copy it exactly into a text code block, then say what to notice in it. Never invent or "tidy" output. If the output depends on an LLM or on time, say that a run may differ.

If the spec lists recordings, the verify run saved them as <lesson dir>/docs/generated/<name>.gif. Show each one next to the output: ![Запуск: маршрутизация трёх обращений](generated/route-tickets.gif). Only link GIFs that exist. If verify logged "skipped" for record, show the text output alone.

Experiments

Turn the spec's experiments into a "what to try" section. For each one: what to change (a concrete edit), what you will observe, and why. Put the explanation in a collapsible block, so the reader can guess first:

1. В `route_ticket` верните `"unknown"` вместо имени очереди и запустите снова.

   <details><summary>Что произойдёт и почему</summary>

   …

   </details>

• Each experiment starts from the lesson's original code. When an experiment changes the code, end its explanation with a reminder to undo the change (git checkout -- . in the lesson directory, or "верните код как было").
• Verify what you predict. Run each experiment in a scratch copy of the lesson directory (outside the course) and describe what really happens, not what the spec expected. If the outcome differs from the spec's experiments entry, correct that entry in .codelabgen/lessons/<id>/spec.yaml too, so the spec stays the source of truth for later lessons.

Glossary terms

The course has a shared glossary (GLOSSARY.md). On the site, every use of a term shows its definition on hover.

• For each term this lesson introduces, add it, in the course language:

  codelabgen glossary add "Граф состояний" --definition "Граф, в котором узлы по очереди обновляют общее состояние." --alias "граф состояний" --lesson <id> --course <dir>

  Use the form the term takes in text as the term. Add inflected forms the text uses as --alias (Russian: "графа", "графе"…), because tooltips match exact words only.
• Link the first use of each term in the notes to its entry. Get the link target from codelabgen glossary link "<term>" --from <lesson dir>/docs/notes.md --course <dir>.
• Check codelabgen glossary list first. Don't redefine terms that earlier lessons introduced, but you may link to them.
• Definitions: one or two sentences, self-contained, without Markdown links.
• Never use an everyday word as a term or alias. Tooltips attach to every exact occurrence on the site, in every lesson. A term like "Поток" (thread) with aliases "поток", "потока" would tooltip unrelated uses of the word ("поток данных"). Use the specific form instead: thread, thread_id, "поток (thread)". Distinctive technical words such as checkpointer, reducer, StateSnapshot and their inflections are fine.

Diagrams, math, callouts

• Follow the diagramming skill. Use Mermaid by default; generate the diagram from the code when the library can draw it.
• Math: only $…$ (inline) and $$…$$ (block, on its own lines).
• Callouts in GitHub alert syntax:

  > [!WARNING]
  > Узел должен возвращать только изменённые поля …

  Use NOTE for asides, TIP for practical advice, WARNING for common mistakes, IMPORTANT for must-know facts.
• Only syntax that renders on GitHub and the site: no !!! admonitions, content tabs, code annotations or --8<--.

Further reading

List only sources you actually read for this chapter, with title and URL, official docs first. Never invent a URL; check each one with WebFetch.

Before you finish

1. codelabgen snippets sync <id> --course <dir>, then codelabgen check snippets <id> --course <dir> must print ok.
2. Every relative link points to an existing file. Every external link was fetched.
3. Every diagram follows the diagramming skill's rules.
4. codelabgen check links --course <dir>, check render and check math report nothing for this lesson's files.