Document the comparison-loop lesson from the strings fix

After fixing strings to include 'café' in the byte-count comparison
loop, audited 109 examples for similar gaps.

Two probes:
  - Find cells with explicit comparison loops `for ... in [(...)]:`
    iterating over 2-3 items. Found 5; only strings was a topic
    spectrum (English / French / Thai). The other 4 (for-loops,
    collections-module, async-await, async-iteration-and-context)
    iterate over example names or async features — not category
    spectrums needing a stepping stone.
  - Find examples whose summary enumerates 3+ named items but
    whose first cell mentions only 1-2 of them. Heuristic was
    noisy: 60 hits, all false positives on closer inspection.
    The truly-three-category examples (numbers, comprehensions,
    runtime-type-checks, classmethods-and-staticmethods,
    structured-data-shapes, truth-and-size) spread the categories
    across separate cells instead of one comparison loop. That's
    a valid pedagogy — one cell per category, building up.

Conclusion: the strings fix was the only actionable case. Recorded
the narrow lesson in docs/lessons-learned.md so future
comparison-loop cells start with the spectrum filled out.

No code or contracts changed. The heuristic for "missing topic
category" is too topic-specific to mechanise as a contract; this
stays guidance.

Author: claude

docs/lessons-learned.md

@@ -111,3 +111,4 @@ git diff --check
 - **Mono character alignment uses the font's advance, not eyeballed pixels.** JetBrains Mono advances ~6px per char at fs=10. A dashed line marking the `/` at index 12 of `def f(a, b, /, c, d): …` lives at `x=12*6+3=75`, not `x=82`. Hand-tuned positions drift; computed positions match the rendered glyph.
 - **Lines must terminate AT elements, not in their gaps or interiors.** A 1.5px gap between a tree edge and a leaf dot reads as "the tree is disconnected" (the `exception-group-peel` bug). A line endpoint 2px inside a circle reads as "the arrow pierces the node" (the `context-bowtie` bug). When connecting to a dot, end the line at the dot's centre and let the dot draw on top — the visual termination is the circumference, with zero gap or overshoot.
 - **Journey pages don't yet render section figures inline.** Production journey pages (`/journeys/<slug>`) currently render the section overview, title, and example list — but no figures. The journey-section figures defined in `scripts/build_prototypes.py JOURNEY_SECTION_FIGURES` only show on the `/prototyping/journey-figures-gestalt` review page. The figures are production-quality and audited, but the rendering surface that would carry them on `www.pythonbyexample.dev` hasn't been built. Open question: do journey pages benefit from inline figures, or do they belong to the lesson pages only?
+- **An explicit comparison loop should iterate over the topic's whole spectrum.** When a cell teaches by doing `for label, value in [(...), (...)]: print(...)`, the bracketed list IS the lesson. Two items is a binary contrast; three items reads as a progression. The strings example presented English (pure ASCII, 1 byte/char) against Thai (3 bytes/char) but skipped the Latin-extended middle (French `café`: 4 code points, 5 bytes — `é` is 2 UTF-8 bytes). Adding the middle row turned the cell from "ASCII vs non-Latin" into "1-byte / 2-byte / 3-byte progression." The rule is narrow — most examples spread categories across cells, which is also a valid pattern — but when a comparison loop exists, fill it with the topic's actual spectrum, not just the endpoints.