Consolidate build into one root Makefile; split run.sh into run-engine.sh/run-interpreter.sh

CLAUDE.md

@@ -16,15 +16,17 @@ built so it can be linked straight into it later without rework (see
 ## Build & run
 
 ```bash
-cd engine
-make          # builds dist/deck-engine, dist/img/, dist/i18n/, dist/run.sh, dist/user.properties
-make test     # builds and runs engine/tests/smoke_test.c
-make clean    # removes build/ and the generated binary/img/i18n (never touches dist/user.properties)
+make          # builds dist/{deck-engine,interpreter-cli}, dist/img/, dist/i18n/,
+              # dist/run-engine.sh, dist/run-interpreter.sh, dist/user.properties
+make test     # builds and runs engine/tests/smoke_test.c and interpreter/tests/*_test.c
+make clean    # removes build/ and the generated binaries/img/i18n (never touches dist/user.properties)
 ```
 
-Build output goes to `dist/`, a sibling of `engine/` and `res/` (not
-inside `engine/`). There is no `make install`; `dist/` is meant to be run
-in place.
+A single `Makefile` at the repo root builds both `engine/` and
+`interpreter/` — there is no per-module Makefile, and no `cd` needed
+before running `make`. Build output goes to `dist/`, a sibling of
+`engine/`, `interpreter/`, and `res/`. There is no `make install`;
+`dist/` is meant to be run in place.
 
 Two ways to run a reading:
 
@@ -35,17 +37,22 @@ dist/deck-engine --seed "2026-07-03" \
   --birth-lat 52.5200 --birth-lon 13.4050 \
   [--date YYYY-MM-DDTHH:MM] [--format text|html|json] [--lang en|de] [--i18n-dir <path>]
 
-# 2. dist/run.sh [text|html] [lang] — wraps the binary for daily use: seed
-#    and --date come from the OS clock (today's date / current UTC time),
-#    birth data + default language are read from dist/user.properties
-#    next to the script; the optional [lang] arg overrides that language
-#    for a single run.
+# 2. dist/run-engine.sh [text|html|json] [lang] — wraps the binary for
+#    daily use: seed and --date come from the OS clock (today's date /
+#    current UTC time), birth data + default language are read from
+#    dist/user.properties next to the script; the optional [lang] arg
+#    overrides that language for a single run.
 ```
 
 `dist/user.properties` is seeded once from `engine/scripts/user.properties.template`
 with placeholder values (`YOUR_BIRTH_DATE_HERE`, etc.) and is **never
-overwritten by later builds** — `run.sh` refuses to run (with a clear
-error) until the placeholders are replaced with real values.
+overwritten by later builds** — `run-engine.sh`/`run-interpreter.sh`
+refuse to run (with a clear error) until the placeholders are replaced
+with real values. `dist/run-interpreter.sh` is the equivalent daily-use
+wrapper for the interpreter: it runs `run-engine.sh`'s same OS-clock
+seed/date and `user.properties` birth data through `deck-engine --format
+json`, piped straight into `dist/interpreter-cli` — see "Interpretation"
+below.
 
 Run a single smoke test by editing `engine/tests/smoke_test.c`'s `main()`
 temporarily, or just read its assertions — there's no test filter flag,
@@ -74,10 +81,10 @@ deck_in_a_dash/
       main.c                     CLI entry point.
     i18n/en.lang, i18n/de.lang   Translation source files, one per language.
     tests/smoke_test.c
-    scripts/run.sh, scripts/user.properties.template
-    Makefile
+    scripts/run-engine.sh, scripts/run-interpreter.sh, scripts/user.properties.template
   interpreter/                  Separate module + binary; see "Interpretation" below.
   dist/                         Build output (gitignored-style; see Build & run).
+  Makefile                      Single root Makefile, builds both engine/ and interpreter/.
 ```
 
 ### Data flow / the real API
@@ -193,14 +200,19 @@ deliberately unchanged by this beyond gaining `--format json`; the two
 binaries compose over that JSON, never by linking together:
 
 ```bash
-cd engine      && make          # -> dist/deck-engine (unchanged; --format json is new)
-cd interpreter && make          # -> dist/interpreter-cli
-cd interpreter && make test     # builds and runs both interpreter/tests/*_test.c
+make          # -> dist/deck-engine (unchanged; --format json is new) and dist/interpreter-cli
+make test     # builds and runs both engine/tests/*_test.c and interpreter/tests/*_test.c
 
 dist/deck-engine ... --format json | dist/interpreter-cli
 # or: dist/deck-engine ... --format json > reading.json && dist/interpreter-cli reading.json
+# or, for daily use (OS clock + user.properties, same as run-engine.sh):
+dist/run-interpreter.sh
 ```
 
+The root `Makefile` builds both from one invocation, but keeps them as
+separate compilation units throughout — no object file is ever shared
+between the two binaries (see the next bullet).
+
 - `interpret_daily_reading(reading, &out)` (`significance.h/.c`) scores
   every aspect in `reading->transits.aspects[]`, keeps the **top 5** by
   score in `DailyInterpretation.top_items[]` (descending, evicting the
@@ -237,8 +249,9 @@ dist/deck-engine ... --format json | dist/interpreter-cli
   today"), makes the whole load fail rather than silently dropping data.
 - **Deliberately header-only dependency on the engine, throughout**:
   `significance.h`/`reading_io.h` `#include engine/src/reading.h` for the
-  struct/enum *definitions*, but `interpreter/Makefile` never compiles or
-  links any engine `.c` file (or the vendored Astronomy Engine) — every
+  struct/enum *definitions*, but the root `Makefile` never compiles or
+  links any engine `.c` file (or the vendored Astronomy Engine) into the
+  interpreter's binary or tests — every
   test in `interpreter/tests/` runs against hand-built JSON text or
   hand-built `DailyReading` values, with no real ephemeris/tarot-draw
   call involved anywhere. Consequently `reading_io.c` (planet/aspect
@@ -251,7 +264,7 @@ dist/deck-engine ... --format json | dist/interpreter-cli
 
 ## Licensing
 
-- Engine code (`engine/src/`, `engine/scripts/`, `engine/Makefile`):
+- Engine code (`engine/src/`, `engine/scripts/`) and the root `Makefile`:
   MIT, per the repo's top-level `LICENSE`.
 - `engine/third_party/astronomy/`: vendored MIT code, unmodified — see
   `VENDORED.md` for the pinned upstream commit.