Add claude docs

.claude/console.md

@@ -0,0 +1,92 @@
+# Console
+
+Source: `src/dusk/console/`
+
+---
+
+## Overview
+
+The console is a lightweight in-engine debug overlay. It maintains a
+fixed-size ring buffer of text lines and can render them to the screen
+as an overlay. On Linux (where `DUSK_CONSOLE_POSIX` is defined), it
+also reads commands from stdin on a background thread, allowing
+interactive input during development without pausing the game loop.
+
+---
+
+## Limits
+
+| Constant | Value |
+|----------|-------|
+| `CONSOLE_LINE_MAX` | 512 chars per line |
+| `CONSOLE_HISTORY_MAX` | 16 lines in the ring buffer |
+| `CONSOLE_EXEC_BUFFER_MAX` | 32 pending execution slots |
+
+---
+
+## Global state
+
+```c
+typedef struct {
+  char_t line[CONSOLE_HISTORY_MAX][CONSOLE_LINE_MAX]; // ring buffer
+  bool_t visible;
+
+  #ifdef DUSK_CONSOLE_POSIX
+    threadmutex_t printMutex;  // guards ring buffer on POSIX targets
+  #endif
+} console_t;
+
+extern console_t CONSOLE;
+```
+
+---
+
+## API
+
+```c
+void consoleInit(void);
+
+// printf-style print into the ring buffer.
+// Thread-safe on POSIX (uses printMutex).
+void consolePrint(const char_t *message, ...);
+
+// Process any queued script input lines. Must be called from the
+// main thread once per frame.
+void consoleUpdate(void);
+
+// Draw the ring buffer as an overlay in UI space.
+errorret_t consoleDraw(void);
+
+void consoleDispose(void);
+```
+
+---
+
+## POSIX stdin mode (`DUSK_CONSOLE_POSIX`)
+
+On Linux only (`DUSK_CONSOLE_POSIX`), the console launches a background
+thread that polls stdin using `poll()` at 75 ms intervals
+(`CONSOLE_POSIX_POLL_RATE`). Lines typed at the terminal are queued
+and dispatched on the main thread by `consoleUpdate()`.
+
+This allows typing commands or JS expressions into the running game
+without blocking the render loop. The ring buffer is protected by
+`CONSOLE.printMutex` so `consolePrint` is safe to call from either
+thread.
+
+POSIX mode is not available on PSP, Vita, or Dolphin targets.
+
+---
+
+## Notes
+
+- `CONSOLE.visible` controls whether `consoleDraw` renders anything.
+  Toggle it from a debug keybind or always set it to `true` in
+  development builds.
+- `consolePrint` wraps lines at `CONSOLE_LINE_MAX` -- long messages are
+  truncated. Use multiple calls for long output.
+- The console is distinct from the error system (`errorThrow` /
+  `errorPrint`). Use `consolePrint` for diagnostic output; use
+  `errorThrow` for recoverable failures.
+- Log calls (`logDebug`, `logError`) go to the platform's debug output
+  (stdout/stderr), not to the console ring buffer.