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/vif_vu.md

@@ -0,0 +1,51 @@
+# VIF/VU Contract
+
+Status: `Draft`
+
+## Purpose
+
+Define the vector-processing cluster and its packet/program interfaces.
+
+## Owns
+
+- VIF0 and VIF1 packet decode/unpack behavior,
+- VU0 and VU1 local code/data memories,
+- microprogram upload path,
+- macro/micro mode coordination as chosen for the implementation scope,
+- synchronization against DMAC and GIF-visible downstream behavior.
+
+## Inputs
+
+- DMAC-fed packet traffic,
+- EE control interactions,
+- memory-backed data where applicable,
+- reset and status/control writes.
+
+## Outputs
+
+- local memory writes,
+- VU execution progress,
+- downstream graphics/data traffic,
+- interrupts/status,
+- trace events.
+
+## Questions to lock
+
+- Is VU0 macro mode required for the first boot milestone?
+- How much VIF unpack coverage is required for the first homebrew target?
+- Do we treat VU execution timing as functionally-correct first or cycle-shaped
+  first?
+
+## Allowed early stubs
+
+- packet capture without execution,
+- microprogram RAM load/observe only,
+- no-op VU execution with trace confirmation.
+
+## Required debug visibility
+
+- packet headers/tags,
+- microprogram loads,
+- local memory writes,
+- VU start/stop,
+- synchronization stalls.