Initial commit: retroDE_ps2 — first-of-its-kind PS2 GS FPGA core (DE25-Nano / Agilex 5)

RTL (GS rasterizer, EE core stub, platform bridge, LPDDR4B path), sim regression
(272 TBs), docs, and tooling. Copyrighted PS2 content (BIOS, game code, GS dumps,
and all dump-derived textures/traces) is excluded via .gitignore and stays local.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/contracts/ee.md

@@ -0,0 +1,50 @@
+# EE Contract
+
+Status: `Draft`
+
+## Purpose
+
+Define what the Emotion Engine-facing block must provide to the rest of the
+system, independent of the eventual core implementation strategy.
+
+## Owns
+
+- R5900 execution core,
+- COP0-visible system behavior owned by the EE block,
+- FPU/MMI behavior as implemented by the EE-side compute engine,
+- exception and interrupt intake on the EE side,
+- request generation onto EE-visible memory and I/O space.
+
+## Inputs
+
+- clocks/resets,
+- interrupts,
+- memory read/write responses,
+- DMAC/VIF/VU/GS-visible status signals as needed by software-facing I/O.
+
+## Outputs
+
+- instruction fetches,
+- data reads/writes,
+- coprocessor-side requests,
+- interrupt acknowledge / exception state transitions,
+- debug trace events.
+
+## Questions to lock
+
+- Is the EE treated as an imported core behind a wrapper or as locally-owned RTL?
+- What minimum COP0/TLB behavior is required for the first BIOS milestone?
+- Which FPU edge cases are correctness-critical versus deferrable?
+
+## Allowed early stubs
+
+- fetch-only or reduced decode EE stub for memory-map bring-up,
+- reduced exception model for pre-BIOS milestones,
+- trace-only execution harness.
+
+## Required debug visibility
+
+- PC stream,
+- exception vector entries,
+- uncached/cached access origin tags when applicable,
+- selected register snapshots around traps and branches.