guides/templates/Format/EndGuide.md

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

FORMAT
- A4 portrait, 50–250 pages (topic-dependent — small topic short,
  large topic long; the page count follows from the inventory)
- @page { size: A4; margin: 18mm; }
- Cover page + automatic table of contents
- Footer: page number center, "<Topic> EndGuide" right

COVERAGE (highest guide tier)
- ALL building blocks of the topic — complete, "rather too much than too little".
- From the very first line up to expert topics (architecture, internals,
  operations — whatever the expert tier is for the topic).
- Name the current version of the topic as the target version.

TOPIC INVENTORY (binding)
- The inventory is produced beforehand by a research agent and supplied with
  the task. It is the binding list of material: 1 inventory item = 1 OWN H2
  section following the pattern Title·Explanation·Example.
- Do NOT merge, trim, or condense items while writing — if the workload feels
  too large, work part by part instead of compressing.
- Derive parts and chapters from the inventory: group related items into
  chapters, chapters into parts. There is NO default number of parts/chapters.

TARGET AUDIENCE — FROM BEGINNER TO EXPERT
- Starts at zero, progresses step by step across the parts
- Early parts explain every term; later ones assume what came before
- Forward references ("own part") are allowed — the guide is read cover to
  cover or used for lookup

CORE PRINCIPLE — TITLE · EXPLANATION · EXAMPLE (the defining pattern)
- EVERY concept in exactly this order:
  1. Title: pure concept/verb/type name. Nothing else.
  2. Explanation: max. 3 short main clauses, simply worded, no nested
     sentences. Names the functions/building blocks and what they do.
     Recommendations, real-world problems, and warnings do NOT belong in the
     explanation — that is what callouts (tip/warn/note) are for.
  3. Example: runnable code (or a concrete example) with the visible result
     as a comment.
- The heading NEVER carries the function list or the definition:
  - bad:  "Ersetzen: str_replace & substr_replace"
          "object – Instanz einer Klasse"
  - good: "Ersetzen"  + explanation names the functions + example
          "object"     + explanation "Instanz einer Klasse" + example

CONTENT PRINCIPLES
- Completeness: enumerable sets ALWAYS complete (all operators, all variants,
  all modes …). Only very large sets (e.g. hundreds of format characters) as
  a selection + reference to the docs.
- Show the mechanics: examples are real, runnable mini-demos WITH output —
  not just signatures or empty interfaces. For patterns/interfaces:
  contract + concrete implementation + call with visible result.
- Depth before enumeration: explain why/when first, then show.
- No performance numbers without a source.

CODE CONVENTIONS (for technical topics)
- Identifiers in English: variables, functions, classes, methods, constants.
- German stays: prose, headings, code comments, output strings,
  sample data ("Anna", "Köln", "Hallo Welt").
- Unchanged: topic-/language-native names (built-ins, standard APIs);
  table/column names in strings (= data, not identifiers).
- Result comment on every example:  // 19.99 €
- Neutral data: names Anna/Ben/Tom, places Köln/Hamburg, mail@example.com.
  No personal or real data.
- Prefer modern syntax of the current target version; mark version-dependent
  features ("seit Version X").

STRUCTURE
1. Cover: logo, title "<Topic> — Der EndGuide", subtitle, badge
   "<N> Teile · <M> Kapitel" (numbers taken from the inventory)
2. Table of contents (generated automatically from the structure)
3. Per part: divider page (part number · title · description · chapter list)
4. Per chapter: chapter number + title, short lead sentence, then H2 sections
   following the pattern Title·Explanation·Example

NUMBERING
- Parts and chapters are SEPARATE counters.
- Chapters run through the whole guide — they do NOT restart per part.
- "Teil 7" ≠ "Kapitel 7".

ELEMENTS
- Body text: justify; explanations as prose, bullet lists sparingly.
- Code blocks: dark background, syntax highlighting, with result comments.
- Inline code: light background, accent color — for every technical term and
  function name in prose.
- Callouts in 3 flavors: tip (✓), warn (!), note (i). Sparingly, at most
  one per section.
- NO overview or reference tables. Every function/feature gets
  explanation + example inline.

TYPOGRAPHY & COLORS (max 3 + neutrals)
- Accent color: lean on the topic's official color; dark code blocks
  (#1e2a3a family).
- Body serif; headings sans-serif bold; code monospace.
- max. 3 font sizes per section.

CALLOUT USAGE
- tip (✓):  best practice / recommendation.
- warn (!): security issue or pitfall.
- note (i): background / distinction.
- MANDATORY: sentences like "Empfehlung: …", "In der Praxis problematisch: …",
  "Achtung: …" ALWAYS go into the matching callout, never into the running
  prose of the explanation. This keeps the explanation short and the hints
  scannable.

BUILD ARCHITECTURE (structure-driven)
- One source of truth: STRUCTURE in build.py = list of
  (part kicker, title, description, [chapter titles]) — derived directly from
  the inventory. Order, numbers, table of contents, and divider pages are
  generated from it automatically.
- Content in modules content_partN.py:  CHAPTERS = { "chapter title": body_html }.
  Write part by part — never the whole guide in one go. After each part:
  count the H2 sections against that part's inventory items, add anything
  missing immediately, only then start the next part.
- build.py reports the total number of H2 sections at the end; it must match
  the number of inventory items.
- Highlight span classes in code:
  c=comment, k=keyword, s=string/number, f=function,
  t=type/class/constant, v=variable, a=attribute.
  Inline code in prose: <code class="inline">.
- Escaping in code: < > & as &lt; &gt; &amp; (e.g. -&gt;, =&gt;, &amp;&amp;).
- scrub() filters out personal leftovers (names/places/emails) during build.

AVOID
- Fixed part/chapter/page counts as a target (scope follows from the
  inventory, not the other way around).
- Merging or dropping inventory items.
- Function list or definition in the heading (the title stays pure).
- Explanations longer than 3 sentences or with nested sentences.
- Recommendations/warnings in running prose instead of in a callout.
- Overview/reference tables without explanatory text.
- German code identifiers.
- Personal or real data.
- Incomplete enumerable sets.
- Pure interface/signature stubs without call + output.
- Performance numbers without a source.
- Code block or callout torn across a page break
  (page-break-inside: avoid).

GENERATION & VERIFICATION
1. Read the inventory, derive STRUCTURE from it.
2. python3 build.py            → guide.html (reports chapters/parts + sections)
3. weasyprint guide.html guide.pdf
4. Verify — the target values come from the inventory:
   - grep -c 'toc-part'    == number of parts in STRUCTURE
   - grep -c 'chapter-num' == number of chapters in STRUCTURE
   - grep -c '<h2'         == number of inventory items (1 item = 1 section;
     on mismatch: write out the missing items — do NOT trim the inventory)
   - grep -c '<table>'     == 0
   - no real names/places/emails
   - page count (pdfinfo) within the 50–250 range
5. Render samples (pdftoppm) and inspect:
   - Heading = pure title, explanation below it, then the example?
   - Code in English, explanation and comments in German?
   - Code blocks/callouts not torn across page breaks?
   - Cover, table of contents, and part dividers correct?

CHECKLIST PER SECTION
- [ ] Heading is a pure title (no function list, no definition)
- [ ] Explanation in prose present, names the building blocks
- [ ] Explanation max. 3 short main clauses, no nested sentences
- [ ] Recommendations/warnings as callout, not in running prose
- [ ] runnable example with result comment
- [ ] no table
- [ ] English identifiers, German explanation/comments/data
- [ ] enumerable set complete
- [ ] neutral sample data

INSTALLATION
- pip install weasyprint
- apt install poppler-utils   (pdfinfo, pdftoppm, pdftotext)

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.