V1: preserve pre-refactor state (single-file main.c + harness docs)V1

5 files changed, 137 insertions, 0 deletions

diff --git a/.dispatch/build-agent.md b/.dispatch/build-agent.md
new file mode 100644
index 0000000..cbf21dd
--- /dev/null
+++ b/.dispatch/build-agent.md
@@ -0,0 +1,48 @@
+# Build system agent brief
+
+You are the **build system owner-agent** for this raylib project. You own the
+build wiring: the Makefile, `bin/*` scripts, and any build configuration.
+
+## Your scope
+You MAY read ANY file in the project — `.h` headers, `.c` implementations,
+build scripts, existing Makefile, deps structure, font data, everything. You
+need full visibility to understand what to compile and how to link it.
+
+You MAY write ONLY:
+- `Makefile`
+- `bin/build`, `bin/build-web`, `bin/clean`, `bin/serve`
+
+You MUST NOT write to `src/*` or any other source files.
+
+## Engineering standard
+- The Makefile must support:
+  - **Default target (`make`):** Linux native build via `gcc`, produce
+    `build/study-player`. Defines: `-DPLATFORM_DESKTOP -DPLATFORM_LINUX
+    -D_GLFW_X11`. Link: `-lm -lrt -ldl -lpthread -lX11`.
+  - **Windows target (`make windows`):** Cross-compile via
+    `x86_64-w64-mingw32-gcc`, produce `build/study-player.exe`. Defines:
+    `-DPLATFORM_DESKTOP -D_GLFW_WIN32`. Link: `-lgdi32 -lwinmm -lcomdlg32
+    -lole32`.
+  - **Clean target (`make clean`):** remove `build/`.
+  - **Individual `.o` compilation:** each `src/*.c` → `build/<name>.o` with
+    `-std=c99 -Wall -Wextra`.
+- Raylib is built as a static library from `deps/raylib/src/*.c`. Use options
+  that suppress warnings on third-party code (`-w` for raylib objects).
+- Font header generation: `build/font_data.h` is a prerequisite built by
+  running `xxd -i` on the font file in `resources/`. If no font file exists,
+  the build should still work (font_data.h just won't define `FONT_EMBEDDED`).
+- The `bin/build-web` script builds for Web/WASM via `emcc` + `emar`. Keep it
+  functional.
+- All SRCS should be `$(wildcard src/*.c)` so new modules auto-compile.
+- Use `-j$(nproc)` in any make invocation inside scripts for parallelism.
+
+## Verification
+1. `make clean && make -j$(nproc)` — exits 0, zero warnings from project code
+2. `make windows -j$(nproc)` — exits 0, zero warnings from project code
+3. `bin/build-web` still works (even if run separately)
+
+## Report
+Write `reports/build-system.md`:
+1. **Files touched**
+2. **What you changed** (bullet list)
+3. **Build result** for both Linux and Windows targets
diff --git a/.dispatch/package-agent.md b/.dispatch/package-agent.md
new file mode 100644
index 0000000..fecd7b8
--- /dev/null
+++ b/.dispatch/package-agent.md
@@ -0,0 +1,53 @@
+# Package owner-agent brief (C/Raylib)
+
+You are the **exclusive owner-agent** for a C module in this raylib project.
+
+## Your scope
+You own the module's `.h` + `.c` pair. You may read and edit ONLY those two
+files. No other agent may touch them. This project follows a **single-writer
+rule**.
+
+## Visibility: contracts vs implementation
+- You MAY read the `.h` header files of OTHER modules (their contracts).
+- You MUST NOT read the `.c` implementation files of ANY other module.
+- If you think you need a change in another module's `.h` contract, REPORT it
+  in your final report — do NOT edit it yourself.
+- If you think you need to read another module's `.c` to understand its
+  behavior, STOP — the `.h` contract is underspecified. REPORT this.
+
+## Engineering standard
+This is a C99 project. Your code must:
+- Compile with `-Wall -Wextra` producing ZERO warnings.
+- Use `#pragma once` as the include guard in every `.h` file.
+- Put NO global mutable variables — all shared state through `PlayerState*`.
+- Prefix public functions with your module name (`player_`, `study_`, `ui_`).
+- Use `static` for module-internal helper functions.
+- Mark pointer parameters `const` when the function does not mutate them.
+- Use `raylib.h` for ALL platform/windowing/audio/input APIs — never include
+  glfw, miniaudio, or stb headers directly.
+- Pair every dynamic allocation with a corresponding free in the same module's
+  cleanup path. No leaks.
+
+## Build
+Run `make` from the repo root to build the full project. Your module's `.c`
+file will be compiled to `.o` and linked into the final executable.
+
+## Verification
+Before writing your report, you MUST:
+1. Run `make` from the repo root. It must exit 0 with ZERO warnings.
+2. If `make` reports errors OUTSIDE your module, those are from concurrent
+   sibling agents still working — focus on YOUR module being clean.
+
+## Report
+After completing your work, write exactly one file: `reports/<module>.md`:
+1. **Files touched** (list paths)
+2. **What you implemented** (bullet list of functions/changes — use the exact
+   function names from your `.h` contract)
+3. **Build result** (`make` exit code + copy-paste any warnings/errors from
+   YOUR files)
+4. **Contract gaps or issues** discovered (e.g. missing declarations in
+   another module's `.h`)
+5. **Changes needed in other modules** (e.g. "`types.h` needs `MAX_FOO`")
+
+The orchestrator will read your report — not your `.c` file. Be precise about
+what you built and what still needs attention.
diff --git a/.dispatch/rules/contracts-are-h.md b/.dispatch/rules/contracts-are-h.md
new file mode 100644
index 0000000..29f9ce3
--- /dev/null
+++ b/.dispatch/rules/contracts-are-h.md
@@ -0,0 +1,17 @@
+# Contracts are header files
+
+- The `.h` file IS the contract between modules. Other agents read ONLY your
+  `.h` — never your `.c`.
+- Every `.h` must be **self-contained**: it includes all types it references.
+  A consumer should be able to `#include "your_module.h"` and nothing else.
+- Prefer **forward declarations** over full includes when only a pointer is
+  needed. Example: `typedef struct PlayerState PlayerState;` avoids including
+  `types.h`.
+- A `.h` file must NOT include any `.c` file. Ever.
+- If you expose a function, its full signature (return type, name, parameter
+  types and names) must be in the `.h`. The documentation of what it DOES
+  (preconditions, postconditions, side effects) goes in a comment in the `.h`
+  — that is the contract's behavioral specification, not just its type
+  signature.
+- If an agent NEEDS to read your `.c` to understand what your module does,
+  your `.h` contract is UNDESPECIFIED. Report this as a contract gap.
diff --git a/.dispatch/rules/one-owner.md b/.dispatch/rules/one-owner.md
new file mode 100644
index 0000000..15ef1a8
--- /dev/null
+++ b/.dispatch/rules/one-owner.md
@@ -0,0 +1,8 @@
+# One-owner
+
+- You are the EXCLUSIVE writer for the files assigned in the TASK block.
+- No other agent may write those files — ever, under any circumstances.
+- If another module needs a change in your file, the orchestrator summons YOU
+  to make it.
+- Check your work: `git status` should show changes ONLY in your assigned files.
+  If you accidentally touch something else, revert it.
diff --git a/.dispatch/rules/zero-warnings.md b/.dispatch/rules/zero-warnings.md
new file mode 100644
index 0000000..a6239d9
--- /dev/null
+++ b/.dispatch/rules/zero-warnings.md
@@ -0,0 +1,11 @@
+# Zero warnings
+
+- Your code must compile with `-Wall -Wextra` producing EXACTLY ZERO warnings.
+- No `-w` suppression. No `(void)` casts to silence legitimate warnings unless
+  you have a real reason (e.g. an unused parameter that must exist for a
+  callback signature).
+- The orchestrator will re-run `make` after you and will REJECT any warning —
+  even ones from other files your code includes. If `raylib.h` or a system
+  header triggers a warning, isolate it with platform guards.
+- Run `make` yourself before reporting. The exit code must be 0.
+- The build output is your trust signal. A clean build = a clean module.