Document lib/ CLI tools and refresh CLAUDE.md to match

Add doc/Python_Scripts.md covering material_flow.py, tro_flow.py,
tro_annotate.py, tro_catalog.py and dxf_registration.py: purpose, CLI
switches, outputs and exit codes.

Update CLAUDE.md, which still described lib/ and doc/ as empty
design-phase scaffolding: reflect the working tooling, the doc/
reorganization (HundM/, 500573_Mubea/, TRO_Katalog/), the moved SCL
templates, and the now-accepted bin/<tool>.bat+.sh wrapper convention.

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

CLAUDE.md

@@ -9,23 +9,33 @@ electrical layout (list of sensors, stoppers, switches, etc.) and generates a **
 of Siemens SCL code** ("TRO" — Transfer Route Object — blocks for a conveyor/material-flow
 control system) that can be imported directly into TIA Portal.
 
-The repository is currently in the **design/analysis phase**: `lib/`, `tests/`, `examples/`,
-and `cfg/` are empty scaffolding directories (see "Standard Programm Template" structure
-below). No generator code has been written yet. What exists today is:
+The repository has moved past pure analysis: `lib/` now holds working Python tooling that
+derives a material-flow graph and a TRO list from a CSV export (ILS 2.0) and can annotate a
+copy of the BricsCAD drawing with the result. What does **not** exist yet is the actual
+SCL-skeleton generator — the step that would emit TIA-Portal-importable SCL from a JSON
+layout model. `tests/` and `examples/` are still empty scaffolding (see "Standard Programm
+Template" below). What exists today is:
 
-- `bin/` — environment/venv management scripts (see "Environment scripts" below)
-- `data/*.scl` — real SCL code extracted from an existing plant ("HundM_Fortna", 5
-  controllers UH01–UH05), used as reference templates for the planned generator
+- `bin/` — environment/venv management scripts, plus one `.bat`/`.sh` wrapper pair per CLI
+  tool in `lib/` (see "Environment scripts" below)
+- `lib/*.py` — CLI tools and libraries that turn a CSV export + BricsCAD DXF into a
+  material-flow graph, a derived TRO list/diagram, and an annotated copy of the drawing.
+  See **`doc/Python_Scripts.md`** for what each script does and which switches it takes.
+- `data/` — input CSV exports (gitignored, not committed)
+- `cad/tro_types.lsp` — generated type list for the BricsCAD `TROEDIT` dialog (written by
+  `tro_annotate.py --emit-lisp`)
+- `cfg/dxf_registration.json` — persisted, verified CSV↔DXF coordinate transform
 - `doc/*.md` — analysis documents that reverse-engineer the SCL patterns and propose the
-  JSON schema / code-generation approach
+  JSON schema / code-generation approach for the generator that's still to be written
 
-Read `doc/` before writing any generator code — it contains the actual domain model this
-project is meant to implement.
+Read `doc/` before writing any generator code — start with `doc/Python_Scripts.md` for the
+existing tooling, then the domain-model documents below; together they contain the actual
+domain model this project is meant to implement.
 
 ## Environment scripts (bin/)
 
-Every script has a `.bat` (Windows) and `.sh` (Linux/macOS) pair. **None of them invoke a
-concrete Python script** — they only manage the environment and virtualenv.
+Every script has a `.bat` (Windows) and `.sh` (Linux/macOS) pair. The four scripts below are
+environment/venv management only — they never invoke a concrete Python script:
 
 | Script | Purpose |
 |---|---|
@@ -34,6 +44,13 @@ concrete Python script** — they only manage the environment and virtualenv.
 | `activate_venv.bat` / `activate_venv.sh` | Calls `setenv`, activates `.venv` (errors if missing — run `install_py` first) |
 | `get_cmd.bat` / `get_cmd.sh` | Calls `setenv`, opens a new shell with the environment variables set |
 
+**Convention:** every CLI tool added to `lib/` gets its own `.bat`/`.sh` wrapper pair in
+`bin/`, named after the module (e.g. `lib/tro_flow.py` → `bin/tro_flow.bat` /
+`bin/tro_flow.sh`). Each wrapper calls `setenv`, activates `.venv` if present, then runs the
+module with `py`/`python3 "%*"`/`"$@"`. This supersedes the old "env-only" rule — see
+`bin/material_flow.bat`, `bin/tro_flow.bat`, `bin/tro_annotate.bat` (+ `.sh`) for the current
+pattern, and `doc/Python_Scripts.md` for what each tool does and which switches it takes.
+
 Typical workflow on Windows:
 
 ```
@@ -48,13 +65,14 @@ bash bin/install_py.sh
 source bin/activate_venv.sh
 ```
 
-Requires Python 3.10+. `requirements.txt` currently has no real dependencies pinned yet
-(placeholders for `pydantic`, `pytest`).
+Requires Python 3.10+. `requirements.txt` pins `pydantic>=2.0.0` (used throughout `lib/`
+for validated models) and `ezdxf>=1.4.0` (DXF read/write, `tro_annotate.py` only); `pytest`
+is commented out as not yet needed.
 
 There is no build/lint/test command configured yet — `tests/` is empty and no test
-runner or linter is set up. Once code exists in `lib/`, use `pytest` (already anticipated
-in `requirements.txt`) and set `PYTHONPATH` via `bin/setenv` first so imports resolve
-against `lib/`.
+runner or linter is set up. Once tests exist, use `pytest` (already anticipated in
+`requirements.txt`, just commented out) and set `PYTHONPATH` via `bin/setenv` first so
+imports resolve against `lib/`.
 
 ## Domain model (from doc/)
 
@@ -62,8 +80,12 @@ The target system is a Siemens TIA Portal / SCL project for automated conveyor/c
 routing, modeled around **TRO** (Transfer Route Object) blocks. Key documents, read in
 this order for onboarding:
 
-1. **`doc/Json_Layout-Konzept.md`** — the core proposal: a JSON file as single source of
-   truth (`plc`, `controlUnits`, `sensors[]`, `conveyors[]`, `tros[]`, `loadingBooms[]`,
+0. **`doc/Python_Scripts.md`** — the existing CLI tooling (`lib/material_flow.py`,
+   `lib/tro_flow.py`, `lib/tro_annotate.py`, plus the `lib/tro_catalog.py` and
+   `lib/dxf_registration.py` libraries they share): what each script does, its switches,
+   inputs/outputs. This is working code, not a proposal — read it before touching `lib/`.
+1. **`doc/HundM/Json_Layout-Konzept.md`** — the core proposal: a JSON file as single source
+   of truth (`plc`, `controlUnits`, `sensors[]`, `conveyors[]`, `tros[]`, `loadingBooms[]`,
    `emptyCarrBuffers[]`, `routing`, `jamAreas[]`, `scanners[]`, `connections[]`,
    `destinations[]`) from which the repetitive, per-topology SCL code in `FB_Main`,
    `FB_CallSensors`, `FC_Direction`, `FC_Call_Jams` would be generated.
@@ -72,34 +94,48 @@ this order for onboarding:
    combinations of one base type (`1Sep` = one separator/stopper) plus reusable
    sub-blocks (`FB_ILS_STRO_Sep`, `FB_ILS_STRO_Switch`, `FB_ILS_STRO_Vario`,
    `FB_BarcodeReaderCognex`, `FB_CarrAccumulate1Sep`). Only `LoadingBoom` is structurally
-   independent.
-3. **`doc/EA-Listen-Analyse.md`** — analyzes the raw I/O list Excel exports
+   independent. `lib/tro_catalog.py` is the executable form of this catalog (name, FB
+   block, sub-components, color, CAD symbol per type).
+3. **`doc/HundM/EA-Listen-Analyse.md`** — analyzes the raw I/O list Excel exports
    (`*_EA.xlsx`/`*_TIA.xlsx`/`*_WSCAD.xlsx`) and companion position/cabling JSON exports,
    and what can vs. cannot be auto-derived from them (signal naming prefixes `BG/SF/DI/BP`
    for inputs, `MB/MA/QA/DQ/FC/PF` for outputs; topology/timing/customCode cannot be
    derived from I/O lists alone — those must come from the JSON model or CAD symbol).
-4. **`doc/BricsCAD_TRO_Symbol.md`** — proposes a BricsCAD block symbol whose attributes
-   feed the JSON `tros[]` entries; documents which fields are captured on the symbol vs.
-   derived from drawing topology or type-based timing defaults.
-5. **`doc/SCL_Analyse_Standardisierung.md`** — cross-controller duplication analysis;
+4. **`doc/HundM/BricsCAD_TRO_Symbol.md`** — proposes a BricsCAD block symbol whose
+   attributes feed the JSON `tros[]` entries; documents which fields are captured on the
+   symbol vs. derived from drawing topology or type-based timing defaults.
+   `lib/tro_annotate.py` implements a first version of this (marker blocks with `ID`/
+   `TYPE`/`FB_BLOCK` attributes), plus the `TROEDIT` BricsCAD dialog (`cad/tro_types.lsp`,
+   generated by `tro_annotate.py --emit-lisp`).
+5. **`doc/HundM/SCL_Analyse_Standardisierung.md`** — cross-controller duplication analysis;
    identifies ~22 blocks duplicated identically across all 5 controllers (candidates for
    a shared library) and flags "version chaos" areas (e.g. `FB_StockRemovalBLKModul*`
    variants) that should NOT be naively merged.
-6. **`doc/suggestion.md`** — a follow-up proposal to collapse the 7 `FB_ILS_MTRO_*`
+6. **`doc/HundM/suggestion.md`** — a follow-up proposal to collapse the 7 `FB_ILS_MTRO_*`
    variants into a single `FB_ILS_MTRO` block driven by an array/config descriptor
    instead of hand-duplicated numbered members (`...1`, `...2`, `Dir1..Dir4`). References
    a not-yet-written `lib/create_skel.py` (`guess_fbtype()`) as the intended generator
-   entry point — this is the planned shape of the generator, not existing code.
+   entry point — this is still the planned shape of the SCL-emitting generator itself;
+   the current `lib/` tooling derives TROs from a layout but does not yet emit SCL.
+7. **`doc/500573_Mubea/TRO_Identifikation_500573.md`** — the derivation rules
+   `lib/tro_flow.py` implements: how to infer a TRO's type from its separator's host
+   object (Gefällestrecke/Strecke/Kreisel) when no I/O list or `FB_Main` exists yet.
+8. **`doc/TRO_Katalog/TRO_Katalog.md`** — central image/concept catalog per TRO type
+   (schematic, real layout image, SCL template, JSON example, CAD symbol attributes);
+   its generated images come from `doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py`
+   (doc-tooling, not part of the generator — see `doc/Python_Scripts.md` §8) built from
+   `doc/TRO_Katalog/connect.ini`.
 
 ### Used libraries (referenced but not vendored)
 
 Most `FB_ILS_MTRO_*` types exist in this repo **only as `.liblink`** references to an
-external `ILSLib` library — the actual FB source is not in this Git repo. `data/*.scl`
-contains the real **call-site/instantiation code** (parametrization in `FB_Main`) for
-those types, not the FB body. Only a few types have local, fully-vendored SCL source
-(`FB_ILS_MTRO_Vario_workStation`, `FB_EmptyCarrBuffer`, `FB_LoadingBoom_INBOUND`,
-`FB_ILS_MTRO_2Sep1Swi` — the last one unused/orphaned). Treat `data/*.scl` as **read-only
-reference material** for pattern extraction, not code to execute or modify.
+external `ILSLib` library — the actual FB source is not in this Git repo.
+`doc/TRO_Katalog/scl_templates/*.scl` contains the real **call-site/instantiation code**
+(parametrization in `FB_Main`) for those types, not the FB body. Only a few types have
+local, fully-vendored SCL source (`FB_ILS_MTRO_Vario_workStation`, `FB_EmptyCarrBuffer`,
+`FB_LoadingBoom_INBOUND`, `FB_ILS_MTRO_2Sep1Swi` — the last one unused/orphaned). Treat
+`doc/TRO_Katalog/scl_templates/*.scl` as **read-only reference material** for pattern
+extraction, not code to execute or modify.
 
 ## Standard Programm Template
 
@@ -107,18 +143,24 @@ This project follows the user's standard Python project scaffold convention:
 
 ```
 sps_skel/
-  bin/       environment scripts (see above)
-  cfg/       config files (INI/JSON) — empty for now
-  data/      input data, gitignored except the .scl reference templates
-  doc/       documentation
+  bin/       environment scripts, plus one .bat/.sh wrapper pair per lib/ CLI tool
+  cad/       generated BricsCAD LISP support (tro_types.lsp) for the TROEDIT dialog
+  cfg/       config files (INI/JSON); dxf_registration.json holds the persisted,
+             verified CSV<->DXF coordinate transform
+  data/      input CSV exports — gitignored, not committed
+  doc/       documentation — see doc/Python_Scripts.md for the CLI tools, plus the
+             domain-model documents listed above
   examples/  example files — empty for now
-  lib/       Python source — empty for now, this is where the generator belongs
+  lib/       Python source, importable via SKEL_LIB on PYTHONPATH — CLI tools and
+             libraries that derive material flow / TRO lists / CAD annotations from a
+             layout (see doc/Python_Scripts.md); the JSON-driven SCL generator itself
+             is not yet written
   log/       gitignored
-  results/   gitignored
+  results/   gitignored — CLI tool output (.dot/.svg/.md/.dxf)
   tests/     unit tests — empty for now
 ```
 
-When adding the generator, put it under `lib/` (importable via `SKEL_LIB` on
-`PYTHONPATH`), keep `bin/*.bat`/`*.sh` scripts environment-only (do not add
-project-specific script invocations to them per the user's convention), and add tests
-under `tests/`.
+When adding the SCL generator, put it under `lib/` (importable via `SKEL_LIB` on
+`PYTHONPATH`), add a `bin/<name>.bat`/`.sh` wrapper pair for it following the pattern of
+`bin/tro_flow.bat`/`.sh` (see "Environment scripts" above), document its switches in
+`doc/Python_Scripts.md`, and add tests under `tests/`.