```
MINI-GUIDE STYLE (HTML/CSS → PDF via WeasyPrint)

FORMAT
- A4 portrait, 3-5 pages
- @page { size: A4; margin: 18mm 18mm 16mm 18mm; }
- Footer: page number center, guide title right

COVERAGE (lowest guide tier)
- ALL core building blocks of the topic — what you need to get started.
  Which ones those are depends on the topic.
- The topic inventory is produced beforehand by a research agent and
  supplied. It is binding: every item gets a section.
- Sections without chapter structure; code examples very short (2-7 lines)
- ~15-25 min reading time, 3-5 pages — this upper limit always applies

TARGET AUDIENCE — COMPACT BEGINNER INTRO
- Real beginners with no programming experience in the topic
- Assumes only general understanding ("what is programming")
- Terms are explained on first appearance
- NO language-character overview for experienced developers
- NO advanced features (even if cool and short)

CONTENT PRINCIPLES
- Show only absolute basics
- Topics someone can reproduce themselves after 15 min
- No tooling complexity (package managers, build systems, compilers)
- No language specialties (type systems, decorators, generics)
- No OOP if possible (or only the most trivial form)
- Depth of explanation before breadth of features
- Better 5 concepts thoroughly than 15 superficially

TYPICAL 5-SECTION STRUCTURE
1. Starting the language — installation, first file, first program
2. Variables — concept + 2-3 basic types
3. Control flow — if/else with a simple example
4. Lists + iteration — array + loop
5. Functions — declaration + call + return value

(This order builds on itself and ends with something meaningful.)

STRUCTURE
1. Compact head: logo left (16mm), title + subtitle center, badge + time right
2. Gap opener: opening question, italic and framed, low-threshold
3. 4-6 H2 sections with explanatory text + code example + optional callout

ELEMENTS
- Body text: justify with hyphenation
- Code blocks: dark background, syntax highlighting, very short (2-7 lines)
- Inline code: light background, accent color
- Tables: only if truly necessary (comparison operators etc.)
- Callouts in 3 flavors: tip (green), warn (red), note (accent color)

TYPOGRAPHY
- Body: 10.5pt serif (Charter), line-height 1.55
- Head h1: 20pt sans-serif bold
- H2 section: 13pt sans-serif bold
- Code: 8.5pt monospace, line-height 1.5
- Inline code: 9pt monospace
- Callout labels: 8pt uppercase, letter-spacing 1pt

COLORS (max 3 + neutrals)
- Accent color: strong, leaning on the topic's official color
- Accent dark: darker variant for accents
- Background soft: light variant of the accent color
- Code background: #1e2a3a
- Text: #1a1a1a / muted #5a6470 / line #d8dde3
- Callout colors: green/red/accent

GAP OPENER (REQUIRED)
- Italic, framed with an accent-color border
- Low-threshold question that the guide answers
- Sparks interest with a relevant statistic or practical angle
- NO technical terms that have not been explained yet
- Examples:
  - "PHP läuft hinter rund drei Viertel aller Webseiten..."
  - "JavaScript ist die Sprache des Webs – aber wie schreibt man das eigentliche Code..."
  - "Python ist die beliebteste Anfänger-Sprache..."

EXPLANATION DEPTH PER CONCEPT
- Name the concept (e.g. "Variable")
- Explain in one sentence what it is
- Code example with comments
- Mention language quirks (e.g. "in PHP beginnen Variablen mit $")
- NO reference to concepts that come later

CALLOUT USAGE
- tip (green): practice suggestion at the end, encouraging
- warn (red): beginner pitfalls ("= vs ==", "vergessenes Semikolon")
- note (accent): background info, explanation of a language quirk

CALLOUT CSS IMPORTANT
- .callout-body > b:first-child with display:block for the label
- NOT .callout-body b globally with display:block (destroys inline bold)

GAP CSS IMPORTANT
- .gap > b:first-child with display:block for the "FRAGE ZUM EINSTIEG" label
- NOT .gap b globally with display:block (destroys inline bold in the
  question text)

TOPIC-SPECIFIC ADJUSTMENTS (choose before generating)
- Accent color: the topic's official color
- Logo letter(s) or abbreviation
- Welcome statistic in the gap opener
- Choose 4-6 beginner topics (see standard structure)

REQUIRED ELEMENTS
- 1 gap opener at the start
- 5-7 code examples (short, 2-7 lines, beginner-friendly)
- At least 1 callout (often: warn for a pitfall, tip for practice at the end)
- Inline code for technical terms

AVOID
- TOC or cover (oversized for 15 min)
- Introductory filler ("In diesem Mini-Guide lernen wir...")
- Claims of completeness (belongs in a larger guide)
- Reference tables without explanatory text (belongs in a cheatsheet)
- Recall or next-step at the end (a mini-guide ends with content)
- Topics that are advanced (even if cool):
  - Type systems, type hints, generics
  - OOP features (except the most trivial form)
  - Tooling (package managers, build, linting)
  - Language specialties (PHP: strict_types, readonly, Composer, PSR-4)
- page break in the middle of a code block or callout
  (page-break-inside: avoid)
- More than 3 font sizes per section
- Floats or absolute positioning (breaks in WeasyPrint)
- Technical terms without explanation
- References to concepts that come later
- Edge cases and "but" sentences

GENERATION WITH FEEDBACK LOOP (max 3 iterations)
1. Write the HTML
2. weasyprint file.html file.pdf
3. PDF to PNGs: convert all pages
4. View all pages
5. Check:
   - Head clean (logo does not overlap the title)?
   - Code blocks not torn across page breaks?
   - Callouts fully visible?
   - Inline bolds in callouts/gap correct (not rendered as blocks)?
   - Footer with page number correct?
   - Would a real beginner understand this?
   - Were all technical terms explained on first appearance?
6. On problems: fix, repeat from step 2
7. Output after max 3 iterations

INSTALLATION
- pip install weasyprint pdf2image
- apt install poppler-utils
```

DARK MODE (REQUIRED)
- Define all colors exclusively via :root variables
  (--ink, --muted, --line, --bg-soft, accent variables).
- Additionally ship a dark-mode block:
  @media screen {
    html[data-theme="dark"] { ...dark variable values... }
    html[data-theme="dark"] body { background: #15171c; }
  }
- The app enables it via data-theme="dark" on <html>.
  Do NOT use prefers-color-scheme.
- Dark values: dark backgrounds (#15171c / #23262e), light text (#e6e8ee),
  muted lines (#2c3038). Lift accent colors so headings and links stay
  readable on a dark background (check contrast). Elements with light text on
  accent backgrounds (e.g. table headers) may keep their light background
  color.
- Do not hardcode callout/infobox backgrounds — or darken them explicitly in
  dark mode (e.g. to var(--bg-soft)); the colored border stays.
- Only inside @media screen — print/PDF stays light.