From 5378bdbc24e36ebebfea48111463d4242912b5dc Mon Sep 17 00:00:00 2001
From: shahondin1624 <shahondin1624@gmail.com>
Date: Tue, 17 Mar 2026 10:01:48 +0100
Subject: [PATCH] docs: update CLAUDE.md to reflect current codebase

Add ForewordParser pipeline step, document all Song/SongLine fields,
Foreword type, ForewordPage variant, BookConfig subtypes, all ChordPro
directives, and new Configuration section for songbook.yaml options.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 46 ++++++++++++++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 93877e8..4185733 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,16 +35,17 @@ Requires Java 21 (configured in `gradle.properties`). Kotlin 2.1.10, Gradle 9.3.
 
 ## Architecture
 
-**Pipeline:** Parse → Measure → Paginate → Render
+**Pipeline:** Parse → Validate → Measure → Paginate → Render
 
 `SongbookPipeline` (in `app`) orchestrates the full flow:
 1. `ConfigParser` reads `songbook.yaml` → `BookConfig`
-2. `ChordProParser` reads `.chopro` files → `Song` objects
-3. `Validator` checks config and songs
-4. `MeasurementEngine` calculates each song's height in mm using `FontMetrics`
-5. `TocGenerator` estimates TOC page count and creates entries
-6. `PaginationEngine` arranges songs into pages (greedy spread packing)
-7. `PdfBookRenderer` generates the PDF via OpenPDF
+2. `ChordProParser` reads `.chopro`/`.cho`/`.crd` files → `Song` objects
+3. `ForewordParser` reads optional `foreword.txt` → `Foreword` (if configured)
+4. `Validator` checks config and songs
+5. `MeasurementEngine` calculates each song's height in mm using `FontMetrics`
+6. `TocGenerator` estimates TOC page count and creates entries
+7. `PaginationEngine` arranges songs into pages (greedy spread packing)
+8. `PdfBookRenderer` generates the PDF via OpenPDF
 
 **Module dependency graph:**
 ```
@@ -62,14 +63,39 @@ app, parser ← gui (Compose Desktop)
 
 ## Key Types
 
-- `Song` → sections → `SongLine` → `LineSegment(chord?, text)` — chord is placed above the text segment
-- `PageContent` — sealed class: `SongPage`, `FillerImage`, `BlankPage`
+- `Song` → sections → `SongLine` → `LineSegment(chord?, text)` — chord is placed above the text segment. Also has `aliases`, `lyricist`, `composer`, `key`, `tags`, `notes: List<String>`, `references: Map<String, Int>` (bookId → page), `capo`
+- `SongLine` — holds `segments` plus optional `imagePath` (when set, the line is an inline image)
+- `Foreword` — `quote`, `paragraphs`, `signatures` — parsed from a plain-text file
+- `PageContent` — sealed class: `SongPage`, `FillerImage`, `BlankPage`, `ForewordPage`
 - `SectionType` — enum: `VERSE`, `CHORUS`, `BRIDGE`, `REPEAT`
+- `BookConfig` — top-level config with `FontsConfig`, `LayoutConfig`, `TocConfig`, `ForewordConfig`, `ReferenceBook` list. `FontSpec.file` supports custom font files. `LayoutConfig.metadataLabels` (`"abbreviated"` or `"german"`) and `metadataPosition` (`"top"` or `"bottom"`) control metadata rendering
 - `BuildResult` — returned by `SongbookPipeline.build()` with success/errors/counts
 
 ## Song Format
 
-ChordPro-compatible `.chopro` files: directives in `{braces}`, chords in `[brackets]` inline with lyrics, comments with `#`. See `songs/` for examples.
+ChordPro-compatible `.chopro`/`.cho`/`.crd` files: directives in `{braces}`, chords in `[brackets]` inline with lyrics, comments with `#`. See `songs/` for examples.
+
+**Metadata directives:** `{title: }` / `{t: }`, `{alias: }`, `{lyricist: }`, `{composer: }`, `{key: }`, `{tags: }`, `{note: }`, `{capo: }`
+
+**Section directives:** `{start_of_verse}` / `{sov}`, `{end_of_verse}` / `{eov}`, `{start_of_chorus}` / `{soc}`, `{end_of_chorus}` / `{eoc}`, `{start_of_repeat}` / `{sor}`, `{end_of_repeat}` / `{eor}`. Section starts accept an optional label. `{chorus}` inserts a chorus reference, `{repeat}` sets a repeat label.
+
+**Notes block:** `{start_of_notes}` / `{son}` … `{end_of_notes}` / `{eon}` — multi-paragraph rich-text notes rendered at the end of a song.
+
+**Inline image:** `{image: path}` — embeds an image within a song section.
+
+**Reference:** `{ref: bookId pageNumber}` — cross-reference to a page in another songbook (configured in `reference_books`).
+
+## Configuration
+
+`songbook.yaml` at the project root. Key options beyond the basics:
+
+- `fonts.<role>.file` — path to a custom font file (TTF/OTF) for any font role (`lyrics`, `chords`, `title`, `metadata`, `toc`)
+- `layout.metadata_labels` — `"abbreviated"` (M:/T:) or `"german"` (Worte:/Weise:)
+- `layout.metadata_position` — `"top"` (after title) or `"bottom"` (bottom of last page)
+- `toc.highlight_column` — abbreviation of the reference-book column to highlight (e.g. `"CL"`)
+- `foreword.file` — path to a foreword text file (default `./foreword.txt`)
+- `reference_books` — list of `{id, name, abbreviation}` for cross-reference columns in the TOC
+- `songs.order` — `"alphabetical"` or `"manual"` (file-system order)
 
 ## Test Patterns