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

@@ -0,0 +1,31 @@
+# retroDE_ps2 Planning Docs
+
+This directory is the working design scaffold for the PS2 core.
+
+Purpose:
+
+- define the intended repository shape before RTL lands,
+- define subsystem boundaries before implementation choices harden,
+- document what each block owns, what crosses the boundary, and how we will
+  validate it.
+
+Recommended reading order:
+
+1. [repo_layout.md](repo_layout.md)
+2. [phase0_checklist.md](phase0_checklist.md)
+3. [contracts/README.md](contracts/README.md)
+4. [stub_module_plan.md](stub_module_plan.md)
+5. [wave2_dma_gif_plan.md](wave2_dma_gif_plan.md)
+6. [wave25_memory_backed_dma_plan.md](wave25_memory_backed_dma_plan.md)
+7. [wave26_multi_beat_dma_plan.md](wave26_multi_beat_dma_plan.md)
+
+Relationship to `references/`:
+
+- `references/` is the research library.
+- `docs/` is the project-definition layer.
+
+Rule of thumb:
+
+- If a file explains PS2 hardware as it exists, it belongs under `references/`.
+- If a file explains how `retroDE_ps2` intends to model, partition, or validate
+  that hardware, it belongs under `docs/`.