Add tests, usage documentation, and .claude/ to .gitignore.

Unit tests for the gii-norm loader, text cleanup, quote extraction,
command recognition (literal sentences from the sample amendment act),
sentence splitting, and command application on a synthetic mini law;
an HTML renderer test including escaping; and an end-to-end smoke test
on the IfSG sample data that skips itself when the (untracked) sample
files are absent.  The README gains a German usage section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Change-Id: I7f02ff349f9c3bd34fa90a2a84678b9e6fad697d

1 files changed, 40 insertions, 0 deletions

diff --git a/README.adoc b/README.adoc
index 1e3252d..ad512f6 100644
--- a/README.adoc
+++ b/README.adoc
@@ -51,6 +51,46 @@ To run the command line application after <<building,building>> it:
 ----
 
 
+[[usage]]
+== Usage
+
+ÄndGgner erzeugt aus einem Stammgesetz und einem Änderungsgesetz eine
+zweispaltige HTML-Synopse (alte Fassung links, neue rechts, Änderungen
+wortweise hervorgehoben).
+
+Eingaben:
+
+* Stammgesetz: XML im gii-norm-Format von
+  https://www.gesetze-im-internet.de/[gesetze-im-internet.de]
+* Änderungsgesetz: BGBl-PDF oder Klartext
+
+[source,shell script]
+----
+java -jar target/aendggner-0.1.0-SNAPSHOT.jar \
+  stammgesetz.xml aenderungsgesetz.pdf -o synopse.html
+----
+
+Wichtige Optionen:
+
+`-o, --output <file>`::
+  Ausgabedatei (Default `synopse.html`; `-` = Standardausgabe).
+`--vollstaendig`::
+  Auch unveränderte Normen in die Synopse aufnehmen.
+`--artikel <n>`::
+  Nur diesen Artikel des Änderungsgesetzes anwenden (Default: alle
+  Artikel, deren Einleitung das Stammgesetz nennt).
+`--extract-only`::
+  Nur den bereinigten Lineartext des Änderungsgesetzes ausgeben. Nützlich,
+  wenn die PDF-Extraktion fehlerhaft ist: Text prüfen, von Hand
+  korrigieren und als Klartextdatei wieder einspeisen.
+
+Erkannt werden die gebräuchlichsten Änderungsbefehle des Handbuchs der
+Rechtsförmlichkeit (Ersetzen, Neufassung, Einfügen, Anfügen, Aufheben,
+Streichen, Umnummerierung). Alles andere — etwa Bereichsbefehle wie
+„Die Absätze 2 bis 4 werden …“ — landet mit Begründung im Abschnitt
+*Manuell prüfen* der Synopse und wird niemals stillschweigend verworfen.
+
+
 == Running the Tests
 
 To build and run the tests: