update

templates/Format/EndGuide.md

@@ -1,16 +1,26 @@
 END-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint)
 
 FORMAT
-- A4 Hochformat, ~120–150 Seiten
+- A4 Hochformat, 50–250 Seiten (themenabhängig — kleines Thema kurz,
+  großes Thema lang; die Seitenzahl folgt aus dem Inventar)
 - @page { size: A4; margin: 18mm; }
 - Cover-Seite + automatisches Inhaltsverzeichnis
-- Footer: Seitenzahl Mitte, "PHP EndGuide" rechts
+- Footer: Seitenzahl Mitte, "<Thema> EndGuide" rechts
 
-UMFANG (höchste Guide-Stufe)
-- 17 Teile, 97 durchnummerierte Kapitel
-- Anspruch: vollständig, "lieber zu viel als zu wenig"
-- Von der ersten Zeile bis zu Experten-Themen (Architektur, Async, Betrieb)
-- Zielversion PHP 8.5
+ABDECKUNG (höchste Guide-Stufe)
+- ALLE Bausteine des Themas — vollständig, "lieber zu viel als zu wenig".
+- Von der ersten Zeile bis zu Experten-Themen (Architektur, Interna, Betrieb —
+  was immer beim Thema die Expertenstufe ist).
+- Aktuelle Version des Themas als Zielversion nennen.
+
+THEMENINVENTAR (verbindlich)
+- Das Inventar wird vorab von einem Recherche-Agenten erstellt und mitgeliefert.
+  Es ist die verbindliche Stoffliste: 1 Inventar-Punkt = 1 EIGENE H2-Sektion
+  nach dem Muster Titel·Erklärung·Beispiel.
+- Punkte beim Schreiben NICHT zusammenfassen, kürzen oder eindampfen — wirkt
+  das Pensum zu groß, Teil für Teil abarbeiten statt komprimieren.
+- Teile und Kapitel aus dem Inventar ableiten: verwandte Punkte zu Kapiteln
+  gruppieren, Kapitel zu Teilen. Es gibt KEINE Vorgabe-Zahl für Teile/Kapitel.
 
 ZIELGRUPPE — VOM ANFÄNGER ZUM EXPERTEN
 - Beginnt bei null, steigert sich progressiv über die Teile
@@ -22,46 +32,46 @@ KERNPRINZIP — TITEL · ERKLÄRUNG · BEISPIEL (das definierende Muster)
 - JEDES Konzept in genau dieser Reihenfolge:
   1. Titel: reiner Konzept-/Verb-/Typname. Nichts sonst.
   2. Erklärung: 1–3 Sätze Prosa. Nennt die Funktionen/Bausteine und was sie tun.
-  3. Beispiel: lauffähiger Code mit sichtbarem Ergebnis als Kommentar.
+  3. Beispiel: lauffähiger Code (bzw. konkretes Beispiel) mit sichtbarem
+     Ergebnis als Kommentar.
 - Die Überschrift trägt NIE die Funktionsliste oder die Definition:
   - schlecht: "Ersetzen: str_replace & substr_replace"
               "object – Instanz einer Klasse"
-  - gut:      "Ersetzen"  + Erklärung nennt str_replace/substr_replace + Beispiel
-              "object"     + Erklärung "Instanz einer Klasse"          + Beispiel
+  - gut:      "Ersetzen"  + Erklärung nennt die Funktionen + Beispiel
+              "object"     + Erklärung "Instanz einer Klasse" + Beispiel
 
 INHALTLICHE PRINZIPIEN
 - Vollständigkeit: aufzählbare Mengen IMMER komplett (alle Operatoren, alle
-  Zuweisungs-Kurzformen, alle Vergleiche, alle Sortiervarianten …). Nur sehr
-  große Mengen (z. B. Datums-Formatzeichen) als Auswahl + Verweis auf die Doku.
+  Varianten, alle Modi …). Nur sehr große Mengen (z. B. hunderte
+  Formatzeichen) als Auswahl + Verweis auf die Doku.
 - Mechanik zeigen: Beispiele sind echte, lauffähige Mini-Demos MIT Ausgabe –
   nicht nur Signaturen oder leere Interfaces. Bei Mustern/Interfaces:
   Vertrag + konkrete Implementierung + Aufruf mit sichtbarem Ergebnis.
 - Tiefe vor Aufzählung: erst erklären warum/wann, dann zeigen.
 - Keine Performance-Zahlen ohne Quelle.
 
-CODE-KONVENTIONEN
-- Bezeichner englisch: Variablen, Funktionen, Klassen, Methoden, Konstanten,
-  Enum-Fälle.
+CODE-KONVENTIONEN (bei technischen Themen)
+- Bezeichner englisch: Variablen, Funktionen, Klassen, Methoden, Konstanten.
 - Deutsch bleibt: Fließtext, Überschriften, Code-Kommentare, Ausgabetexte,
   Beispieldaten ("Anna", "Köln", "Hallo Welt").
-- Unverändert: PHP-eigene Namen (count, $_GET, int …); SQL-Tabellen-/
-  Spaltennamen in Strings (= Daten, kein PHP-Bezeichner).
+- Unverändert: themen-/spracheigene Namen (Built-ins, Standard-APIs);
+  Tabellen-/Spaltennamen in Strings (= Daten, keine Bezeichner).
 - Ergebnis-Kommentar an jedem Beispiel:  // 19.99 €
 - Neutrale Daten: Namen Anna/Ben/Tom, Orte Köln/Hamburg, mail@example.com.
   Keine personenbezogenen oder echten Daten.
-- Moderne Syntax bevorzugen (match, Enums, Constructor Promotion, readonly,
-  Property Hooks, Pipe |> …). Versionsabhängiges kennzeichnen ("seit 8.4",
-  "PHP 8.5").
+- Moderne Syntax der aktuellen Zielversion bevorzugen; Versionsabhängiges
+  kennzeichnen ("seit Version X").
 
 STRUKTUR
-1. Cover: Logo, Titel "PHP — Der EndGuide", Subtitle, Badge "17 Teile · 97 Kapitel"
+1. Cover: Logo, Titel "<Thema> — Der EndGuide", Subtitle, Badge
+   "<N> Teile · <M> Kapitel" (Zahlen aus dem Inventar)
 2. Inhaltsverzeichnis (automatisch aus der Struktur erzeugt)
 3. Pro Teil: Trennseite (Teil-Nummer · Titel · Beschreibung · Kapitel-Liste)
 4. Pro Kapitel: Kapitel-Nummer + Titel, kurzer Lead-Satz, dann H2-Sektionen
    nach dem Muster Titel·Erklärung·Beispiel
 
 NUMMERIERUNG
-- Teile (1–17) und Kapitel (durchlaufend 1–97) sind GETRENNTE Zähler.
+- Teile und Kapitel sind GETRENNTE Zähler.
 - Kapitel laufen über den ganzen Guide durch – sie starten NICHT je Teil neu.
 - "Teil 7" ≠ "Kapitel 7".
 
@@ -76,30 +86,38 @@ ELEMENTE
   Erklärung + Beispiel inline.
 
 TYPOGRAFIE & FARBEN (max 3 + Neutrals)
-- Hauptfarbe: PHP-Violett; dunkle Code-Blöcke (#1e2a3a-Familie).
+- Hauptfarbe: an offizielle Farbe des Themas anlehnen; dunkle Code-Blöcke
+  (#1e2a3a-Familie).
 - Body Serif; Überschriften Sans-Serif bold; Code Monospace.
 - max. 3 Schriftgrößen pro Sektion.
 
 CALLOUT-NUTZUNG
 - tip (✓):  Best Practice / Empfehlung.
-- warn (!): Sicherheits- oder Stolperfalle (SQL-Injection, Session-Fixation,
-            ungeprüfte Uploads …).
-- note (i): Hintergrund / Abgrenzung ("ORM oder pures PDO?", "nebenläufig ≠
-            parallel").
+- warn (!): Sicherheits- oder Stolperfalle.
+- note (i): Hintergrund / Abgrenzung.
 
 BUILD-ARCHITEKTUR (strukturgetrieben)
 - Eine Quelle der Wahrheit: STRUCTURE in build.py = Liste aus
-  (Teil-Kicker, Titel, Beschreibung, [Kapiteltitel]). Daraus entstehen
-  Reihenfolge, Nummern, Inhaltsverzeichnis und Trennseiten automatisch.
+  (Teil-Kicker, Titel, Beschreibung, [Kapiteltitel]) — direkt aus dem
+  Inventar abgeleitet. Daraus entstehen Reihenfolge, Nummern,
+  Inhaltsverzeichnis und Trennseiten automatisch.
 - Inhalt in Modulen content_partN.py:  CHAPTERS = { "Kapiteltitel": body_html }.
+  Teil für Teil schreiben — nie den ganzen Guide in einem Stück. Nach jedem
+  Teil: H2-Sektionen gegen die Inventar-Punkte des Teils zählen, Fehlendes
+  sofort ergänzen, erst dann den nächsten Teil beginnen.
+- build.py meldet am Ende die Gesamtzahl der H2-Sektionen; sie muss der
+  Anzahl der Inventar-Punkte entsprechen.
 - Highlight-Span-Klassen im Code:
   c=Kommentar, k=Keyword, s=String/Zahl, f=Funktion,
-  t=Typ/Klasse/Konstante/Enum-Fall, v=Variable, a=Attribut.
+  t=Typ/Klasse/Konstante, v=Variable, a=Attribut.
   Inline-Code im Text: <code class="inline">.
 - Escaping im Code: < > & als &lt; &gt; &amp; (z. B. -&gt;, =&gt;, &amp;&amp;).
 - scrub() filtert beim Bauen personenbezogene Reste (Namen/Orte/Mails) heraus.
 
 VERMEIDEN
+- Feste Teile-/Kapitel-/Seitenzahlen als Ziel (der Umfang folgt aus dem
+  Inventar, nicht umgekehrt).
+- Inventar-Punkte zusammenfassen oder weglassen.
 - Funktionsliste oder Definition in der Überschrift (Titel bleibt rein).
 - Übersichts-/Referenztabellen ohne Erklärtext.
 - Deutsche Code-Bezeichner.
@@ -111,21 +129,20 @@ VERMEIDEN
   (page-break-inside: avoid).
 
 GENERIERUNG & PRÜFUNG
-1. python3 build.py            → guide.html (meldet Kapitel/Teile + Fortschritt %)
-2. weasyprint guide.html guide.pdf
-3. Auslieferung nach /mnt/user-data/outputs: cp html und cp pdf als GETRENNTE
-   Befehle ausführen – NICHT mit && nach einem grep verketten (grep gibt bei 0
-   Treffern Exit 1, bricht die Kette ab → eine Datei würde stillschweigend fehlen).
-4. In /outputs verifizieren:
-   - pdfinfo PHP-EndGuide-Neu.pdf | grep Pages          (Seitenzahl)
-   - grep -c 'toc-part'                                 (= 17 Teile)
-   - grep -c 'chapter-num'                              (= 97 Kapitel)
-   - grep -c '<table>'                                  (= 0)
-   - grep -coE 'echte Namen/Orte/Mails'                 (= 0)
+1. Inventar lesen, STRUCTURE daraus ableiten.
+2. python3 build.py            → guide.html (meldet Kapitel/Teile + Sektionen)
+3. weasyprint guide.html guide.pdf
+4. Verifizieren — die Sollwerte kommen aus dem Inventar:
+   - grep -c 'toc-part'    == Anzahl Teile in STRUCTURE
+   - grep -c 'chapter-num' == Anzahl Kapitel in STRUCTURE
+   - grep -c '<h2'         == Anzahl Inventar-Punkte (1 Punkt = 1 Sektion;
+     bei Differenz: fehlende Punkte ausarbeiten — NICHT das Inventar kürzen)
+   - grep -c '<table>'     == 0
+   - keine echten Namen/Orte/Mails
+   - Seitenzahl (pdfinfo) im Rahmen 50–250
 5. Stichproben rendern (pdftoppm) und ansehen:
    - Überschrift = reiner Titel, Erklärung darunter, dann Beispiel?
    - Code englisch, Erklärung und Kommentare deutsch?
-   - SQL-Strings als Daten unverändert?
    - Codeblöcke/Callouts nicht über Seitenumbruch zerrissen?
    - Cover, Inhaltsverzeichnis und Teil-Trennseiten korrekt?
 

templates/Format/Guide.md

@@ -35,7 +35,11 @@ A guide is a short book. The structure is always the same three levels:
 - **Chapter** — one focused topic. Chapters flow continuously down the page (they do not force a page break); each is separated from the previous by spacing and its own heading block. **3–10 chapters per part**. Each chapter is numbered sequentially across the whole guide (Chapter 1, 2, 3 … regardless of part).
 - **Section** (`<h2>`) and **sub-section** (`<h3>`) — structure inside a chapter.
 
-Length scales with ambition: a compact guide is ~15–30 pages, a comprehensive one 80–250 pages. Decide based on the request and tell the reader the scope on the cover.
+### Scope — coverage-driven (middle tier)
+
+**10–30 pages, covering all important building blocks of the topic** — everything a practical user needs in real work. More selective than the EndGuide tier ("all building blocks"), far broader than the MiniGuide tier ("core building blocks only"). How much that is depends on the topic.
+
+A **topic inventory** is produced beforehand by a research agent and supplied to you. It is binding: every inventory item must appear in the guide as its own section — do not merge, trim, or drop items. Derive parts and chapters from the inventory; part/chapter counts follow from it, there is no default number. Page count is an outcome within the 10–30 range, never a target. State the resulting scope on the cover (parts · chapters).
 
 ### Voice and content rules (apply to every topic)
 

templates/Format/MiniGuide.md

@@ -2,16 +2,17 @@
 MINI-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint)
 
 FORMAT
-- A4 Hochformat, 3-4 Seiten
+- A4 Hochformat, 3-5 Seiten
 - @page { size: A4; margin: 18mm 18mm 16mm 18mm; }
 - Footer: Seitenzahl Mitte, Guide-Titel rechts
 
-UMFANG (einheitlich mit allen Guide-Stufen)
-- 1 Kapitel (oder besser: 4-6 Sektionen ohne Kapitel-Struktur)
-- ~1500 Wörter Fließtext
-- 5-7 Code-Beispiele (sehr kurz, 2-7 Zeilen)
-- ~15 Min Lesezeit
-- 3-4 Seiten
+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
 
 ZIELGRUPPE — KOMPAKTER ANFÄNGER-EINSTIEG
 - Echte Anfänger ohne Programmier-Vorwissen im Thema