Add CLAUDE.md and README.md documentation

Documents the GA-based seating solver's architecture, config file
chain, and setup/usage for both AI assistants and human contributors.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,100 @@
+# platz
+
+A genetic-algorithm-based solver that assigns people to tables ("Tische") for an event,
+given group memberships, table sizes/neighbor relationships, and a configurable penalty
+scheme. It reads a guest list (XML) and a table layout (INI), searches for a good seating
+using a small custom GA framework, and writes the result to text/CSV output files.
+
+**This is Python 2 code** (print statements, `ConfigParser`, `sets.Set`, `UserList`,
+`string.split`, old-style `raise Exception, "msg"`, `xrange`, `dict.has_key`,
+`dict.iteritems`). It needs a Python 2 interpreter; there are no third-party dependencies
+(standard library only).
+
+## Project structure
+
+```
+platz/
+├── bin/           # launcher scripts (bash + Windows batch)
+├── cfg/           # GA cycle definition and penalty scheme
+├── libs/          # the two Python modules (ga.py, Strukturdaten.py, platz.py)
+└── work/          # per-run input (table layout, guest list) and output
+    ├── test1/
+    └── test2/
+```
+
+- `libs/platz.py` — entry point; wires together config, input data, and the GA run.
+- `libs/ga.py` — generic genetic-algorithm scaffolding (`Loesung`, `Zyklus`, `Farm`).
+- `libs/Strukturdaten.py` — domain model for the seating problem (`Person`, `Gruppe`,
+  `Tisch`, `Strafliste`, `Sitzplatzverteilung`, `XMLConfig`).
+
+## Setup
+
+1. Install a Python 2 interpreter (2.4+; no `pip install` needed, standard library only).
+2. Edit the hardcoded paths at the top of the launcher script for your platform:
+   - `bin/run` (bash): `PLATZ=/Users/sm/develop/python/platz`
+   - `bin/run.bat` (Windows): `PLATZ=h:\develop\python\platz` and `PYTHONSHELL=l:\tools\i486_nt\python24`
+
+   Point `PLATZ` at wherever you checked out this repository.
+
+## Running
+
+From a shell:
+
+```bash
+# Linux/macOS
+source bin/run
+```
+
+```bat
+:: Windows
+bin\run.bat
+```
+
+The launcher sets `PLATZ_CFG`, `PLATZ_LIBS`, `PLATZ_WORK`, adds `PLATZ_LIBS` to
+`PYTHONPATH`, and runs `libs/platz.py`.
+
+### Configuring a run
+
+`cfg/platz.cfg` selects which cycle/penalty config and which working directory
+(`work/<name>/`) to use for a given run:
+
+```ini
+[Config]
+Zyklusdatei=$PLATZ_CFG/zyklus.cfg
+Zyklusart=Easy
+Strafendatei=$PLATZ_CFG/strafen.cfg
+Tischedatei=$PLATZ_WORK/test1/tische.ini
+XMLdatei_Bestellung=$PLATZ_WORK/test1/bestellung.xml
+AusgabeTischePersonen=$PLATZ_WORK/test1/TischePersonen.txt
+AusgabePersonTisch=$PLATZ_WORK/test1/PersonenTische.csv
+```
+
+To run against a different dataset, point the `Tischedatei`/`XMLdatei_Bestellung`/output
+entries at another `work/<name>/` folder, or add a new one following the same layout:
+
+- `tische.ini` — one section per table: `Nummer`, `Hof` (venue/court), `Plaetze` (seat
+  count), `Nachbarliste` (neighboring table ids), `Koordinaten`.
+- `bestellung.xml` — `<Gruppe>` blocks, each with a `<Person>` template
+  (`Vorname`/`Nachname`/optional `Titel`) and an `<Anzahl>` (how many bookings to expand
+  that template into). A `<Gruppe>` containing a `<Tisch>` tag is treated as a VIP group
+  pinned to that table instead of being placed by the GA.
+
+`cfg/zyklus.cfg` defines the GA run schedule ("Zyklus") as an `Abfolge` (sequence of
+actions) and matching `Anzahl` (counts): `e` create, `s` select best, `S` select randomly,
+`m` mutate, `j` keep parents, `z` advance generation.
+
+`cfg/strafen.cfg` defines the penalty scheme: cost of splitting a group across tables (by
+group size and number of splits), cost of a person sitting alone or without a group-mate at
+a neighboring table, and per-table seat-utilization penalties.
+
+### Output
+
+A run writes two files into the configured working directory:
+
+- `TischePersonen.txt` — table → seated people, with venue/table/seat numbers.
+- `PersonenTische.csv` — person → table, sorted alphabetically by name.
+
+## Further details
+
+See `CLAUDE.md` for a deeper architectural walkthrough of the GA framework and domain
+model, intended for AI coding assistants but equally useful for human contributors.