Add claude docs

.claude/engine.md

@@ -0,0 +1,95 @@
+# Engine, System, and Log
+
+Sources: `src/dusk/engine/`, `src/dusk/system/`, `src/dusk/log/`
+
+---
+
+## Engine (`engine.h`)
+
+The engine owns the top-level init / update / dispose loop. Every
+platform's `main()` calls these three functions in order.
+
+```c
+extern engine_t ENGINE;
+// ENGINE.running  -- false causes the main loop to exit
+// ENGINE.argc / ENGINE.argv -- passed from main()
+// ENGINE.version  -- version string
+
+errorret_t engineInit(int32_t argc, const char_t **argv);
+errorret_t engineUpdate(void);   // called once per tick
+errorret_t engineDispose(void);
+```
+
+`engineInit` initialises subsystems in order: system, log, assert,
+display, time, asset, input, physics, script, etc.
+
+`engineUpdate` steps each subsystem: time, input, physics, script, ECS
+entities, rendering, audio, network, asset completion callbacks.
+
+`engineDispose` shuts everything down in reverse order.
+
+**To exit gracefully:** set `ENGINE.running = false` -- the platform
+main loop checks this each tick and calls `engineDispose` before
+returning.
+
+---
+
+## System (`system.h`)
+
+The system module is initialised very early (before most other
+subsystems) and provides two things:
+
+### Platform identity
+
+```c
+typedef enum { SYSTEM_PLATFORM_LIST } systemplatform_t;
+
+systemplatform_t systemGetPlatform(void);
+```
+
+Platform names come from `systemplatformlist.h` via an X-macro. This
+lets game code query the runtime platform when compile-time guards are
+not sufficient (e.g. serializing platform name to a log).
+
+### Dialog blocking
+
+Some platforms (PSP, Wii) show OS-level dialogs (Wi-Fi setup, save
+management) that block the normal game loop. The system module exposes
+the current dialog state so the engine main loop can adjust:
+
+```c
+typedef enum {
+  SYSTEM_DIALOG_TYPE_NONE,
+  SYSTEM_DIALOG_TYPE_RENDER_BLOCKING,  // skip render but still tick
+  SYSTEM_DIALOG_TYPE_TICK_BLOCKING,    // skip both render and tick
+} systemdialogtype_t;
+
+systemdialogtype_t systemGetActiveDialogType(void);
+```
+
+`engineUpdate` checks this before calling render / update code.
+Most platforms always return `SYSTEM_DIALOG_TYPE_NONE`.
+
+---
+
+## Log (`log.h`)
+
+Simple printf-style logging with two levels. Always use these instead
+of `printf` / `fprintf`.
+
+```c
+void logDebug(const char_t *message, ...);
+// Writes to the debug output (stdout on desktop, platform console
+// on handhelds). No-op in release builds on some platforms.
+
+void logError(const char_t *message, ...);
+// Writes to the error output. On some platforms (PSP) this may
+// pause execution to ensure the message is visible before continuing.
+```
+
+**Do not** use `logDebug` / `logError` for structured error handling --
+that is what `errorThrow` / `errorChain` are for. Log calls are for
+human-readable diagnostics only.
+
+The error system calls `logError` internally when printing a caught
+error via `errorPrint()`.