update

templates/Format/MiniGuide.md

@@ -1,168 +1,170 @@
 ```
-MINI-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint)
+MINI-GUIDE STYLE (HTML/CSS → PDF via WeasyPrint)
 
 FORMAT
-- A4 Hochformat, 3-5 Seiten
+- A4 portrait, 3-5 pages
 - @page { size: A4; margin: 18mm 18mm 16mm 18mm; }
-- Footer: Seitenzahl Mitte, Guide-Titel rechts
+- Footer: page number center, guide title right
 
-ABDECKUNG (niedrigste Guide-Stufe)
-- ALLE Kern-Bausteine des Themas — was man braucht, um anzufangen.
-  Welche das sind, hängt vom Thema ab.
-- Das Themeninventar wird vorab von einem Recherche-Agenten erstellt und
-  mitgeliefert. Es ist verbindlich: jeder Punkt bekommt eine Sektion.
-- Sektionen ohne Kapitel-Struktur; Code-Beispiele sehr kurz (2-7 Zeilen)
-- ~15-25 Min Lesezeit, 3-5 Seiten — diese Obergrenze gilt immer
+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
 
-ZIELGRUPPE — KOMPAKTER ANFÄNGER-EINSTIEG
-- Echte Anfänger ohne Programmier-Vorwissen im Thema
-- Setzt nur allgemeines Verständnis voraus ("was ist Programmieren")
-- Begriffe werden bei erstem Auftreten erklärt
-- KEIN Sprach-Charakter-Überblick für erfahrene Entwickler
-- KEINE fortgeschrittenen Features (auch wenn cool und kurz)
+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)
 
-INHALTLICHE PRINZIPIEN
-- Nur absolute Basics zeigen
-- Themen, die jemand nach 15 Min selbst nachmachen kann
-- Keine Tooling-Komplexität (Paketmanager, Build-Systeme, Compiler)
-- Keine Sprach-Spezialitäten (Type-Systeme, Decorators, Generics)
-- Keine OOP, wenn möglich (oder nur trivialste Form)
-- Erklär-Tiefe vor Feature-Breite
-- Lieber 5 Konzepte gründlich als 15 oberflächlich
+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
 
-TYPISCHE 5-SEKTIONEN-STRUKTUR
-1. Sprache starten — Installation, erste Datei, erstes Programm
-2. Variablen — Konzept + 2-3 Basis-Typen
-3. Kontrollfluss — if/else mit einfachem Beispiel
-4. Listen + Iteration — Array + Schleife
-5. Funktionen — Deklaration + Aufruf + Rückgabe
+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
 
-(Diese Reihenfolge baut aufeinander auf und endet mit etwas Sinnvollem.)
+(This order builds on itself and ends with something meaningful.)
 
-STRUKTUR
-1. Kompakter Head: Logo links (16mm), Titel + Subtitle mittig, Badge + Zeit rechts
-2. Gap-Opener: Frage zum Einstieg, kursiv eingerahmt, niedrigschwellig
-3. 4-6 H2-Sektionen mit Erklärtext + Code-Beispiel + ggf. Callout
+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
 
-ELEMENTE
-- Fließtext: justify mit Silbentrennung
-- Codeblöcke: dunkler Hintergrund, syntax highlighting, sehr kurz (2-7 Zeilen)
-- Inline-Code: heller Hintergrund, Hauptfarbe
-- Tabellen: nur wenn wirklich nötig (Vergleichs-Operatoren o.ä.)
-- Callouts in 3 Varianten: tip (grün), warn (rot), note (Hauptfarbe)
+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)
 
-TYPOGRAFIE
-- Body: 10.5pt Serif (Charter), line-height 1.55
-- Head h1: 20pt Sans-Serif bold
-- H2 Sektion: 13pt Sans-Serif bold
-- Code: 8.5pt Monospace, line-height 1.5
-- Inline-Code: 9pt Monospace
-- Callout-Labels: 8pt uppercase, letter-spacing 1pt
+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
 
-FARBEN (max 3 + Neutrals)
-- Hauptfarbe: kräftig, an offizielle Farbe des Themas anlehnen
-- Hauptfarbe-Dunkel: dunklere Variante für Akzente
-- Hintergrund-Soft: helle Variante der Hauptfarbe
-- Code-Hintergrund: #1e2a3a
-- Text: #1a1a1a / muted #5a6470 / Linie #d8dde3
-- Callout-Farben: grün/rot/Hauptfarbe
+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 (PFLICHT)
-- Kursiv, eingerahmt mit Hauptfarbe-Border
-- Niedrigschwellige Frage, die der Guide beantwortet
-- Begeistert mit relevanter Statistik oder Praxis-Bezug
-- KEINE Fachbegriffe, die noch nicht erklärt sind
-- Beispiele:
+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..."
 
-ERKLÄR-TIEFE PRO KONZEPT
-- Konzept benennen (z.B. "Variable")
-- In einem Satz erklären, was es ist
-- Code-Beispiel mit Kommentaren
-- Sprach-Eigenheiten erwähnen (z.B. "in PHP beginnen Variablen mit $")
-- KEIN Verweis auf andere Konzepte, die noch kommen
+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-NUTZUNG
-- tip (grün): Übungs-Anregung am Ende, ermutigend
-- warn (rot): Anfänger-Stolperfallen ("= vs ==", "vergessenes Semikolon")
-- note (Hauptfarbe): Hintergrund-Info, Erklärung einer Sprach-Eigenheit
+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 WICHTIG
-- .callout-body > b:first-child mit display:block für Label
-- NICHT .callout-body b global mit display:block (zerstört Inline-Bold)
+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 WICHTIG
-- .gap > b:first-child mit display:block für "FRAGE ZUM EINSTIEG"-Label
-- NICHT .gap b global mit display:block (zerstört Inline-Bold im Frage-Text)
+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)
 
-THEMENSPEZIFISCHE ANPASSUNGEN (vor Generierung wählen)
-- Hauptfarbe: offizielle Farbe des Themas
-- Logo-Buchstabe(n) oder Kürzel
-- Begrüßungs-Statistik im Gap-Opener
-- 4-6 Anfänger-Themen wählen (siehe Standard-Struktur)
+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)
 
-PFLICHT-ELEMENTE
-- 1 Gap-Opener am Anfang
-- 5-7 Code-Beispiele (kurz, 2-7 Zeilen, anfänger-tauglich)
-- Mindestens 1 Callout (oft: warn für Stolperfalle, tip für Übung am Ende)
-- Inline-Codes für Fachbegriffe
+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
 
-VERMEIDEN
-- TOC oder Cover (überdimensioniert für 15 Min)
-- Einleitungs-Floskeln ("In diesem Mini-Guide lernen wir...")
-- Vollständigkeitsanspruch (gehört in größeren Guide)
-- Referenz-Tabellen ohne Erklärtext (gehört in Cheatsheet)
-- Recall oder Next-Step am Ende (Mini-Guide endet mit Inhalt)
-- Themen, die fortgeschritten sind (auch wenn cool):
-  - Type-Systems, Type-Hints, Generics
-  - OOP-Features (außer trivialster Form)
-  - Tooling (Paketmanager, Build, Linting)
-  - Sprach-Spezialitäten (PHP: strict_types, readonly, Composer, PSR-4)
-- page-break mitten in Codeblock oder Callout (page-break-inside: avoid)
-- Mehr als 3 Schriftgrößen pro Sektion
-- Floats oder absolute positioning (bricht in WeasyPrint)
-- Fachbegriffe ohne Erklärung
-- Verweise auf andere Konzepte, die noch kommen
-- Edge Cases und "aber"-Sätze
+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
 
-GENERIERUNG MIT FEEDBACK-LOOP (max 3 Iterationen)
-1. HTML schreiben
+GENERATION WITH FEEDBACK LOOP (max 3 iterations)
+1. Write the HTML
 2. weasyprint file.html file.pdf
-3. PDF zu PNGs: alle Seiten konvertieren
-4. Alle Seiten ansehen
-5. Prüfen:
-   - Head sauber (Logo überlappt nicht mit Titel)?
-   - Code-Blöcke nicht über Seitenumbruch zerrissen?
-   - Callouts vollständig sichtbar?
-   - Inline-Bolds in Callouts/Gap korrekt (nicht als Blöcke)?
-   - Footer mit Seitenzahl korrekt?
-   - Würde ein echter Anfänger das verstehen?
-   - Wurden alle Fachbegriffe beim ersten Auftreten erklärt?
-6. Bei Problemen: fixen, ab Schritt 2 wiederholen
-7. Nach max 3 Iterationen ausgeben
+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
 ```
 
-DARKMODE (PFLICHT)
-- Alle Farben ausschließlich über :root-Variablen definieren
-  (--ink, --muted, --line, --bg-soft, Akzent-Variablen).
-- Zusätzlich einen Dunkelmodus-Block ausliefern:
+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"] { ...dunkle Variablenwerte... }
+    html[data-theme="dark"] { ...dark variable values... }
     html[data-theme="dark"] body { background: #15171c; }
   }
-- Die App aktiviert ihn über data-theme="dark" auf <html>.
-  KEIN prefers-color-scheme verwenden.
-- Dunkle Werte: Hintergründe dunkel (#15171c / #23262e), Text hell (#e6e8ee),
-  Linien gedämpft (#2c3038). Akzentfarben so anheben, dass Überschriften und
-  Links auf dunklem Grund lesbar bleiben (Kontrast prüfen). Elemente mit hellem
-  Text auf Akzent-Hintergrund (z. B. Tabellenköpfe) dürfen ihre helle
-  Hintergrundfarbe behalten.
-- Callout-/Infobox-Hintergründe nicht hartkodieren oder im Dunkelmodus
-  explizit abdunkeln (z. B. auf var(--bg-soft)); farbige Border bleibt.
-- Nur innerhalb von @media screen — Druck/PDF bleibt unverändert hell.
+- 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.