Add FPGA project workspace layout

CLAUDE.md

@@ -13,20 +13,20 @@ See ROADMAP.md for the full phased plan.
 
 - Language: SystemVerilog (not Verilog). Use SV features: packages, structs, enums,
   always_comb, always_ff, logic (not reg/wire).
-- All inter-stage signals are defined as structs in `rtl/pkg/rv32_pkg.sv`. Always
-  import this package. When adding new functionality, extend the existing structs
-  rather than adding loose wires.
+- All inter-stage signals are defined as structs in `FPGA/rtl/pkg/rv32_pkg.sv`.
+  Always import this package. When adding new functionality, extend the existing
+  structs rather than adding loose wires.
 - Module naming: `rv32_<block>` (e.g., `rv32_alu`, `rv32_decode`, `rv32_regfile`).
 - File naming: one module per file, filename matches module name.
-- Testbenches: `tb/tb_<module>.sv`. Use Vivado simulator.
+- Testbenches: `FPGA/tb/tb_<module>.sv`. Use Vivado simulator.
 - Clock: single clock domain, active rising edge, signal named `clk`. Target
   frequency: 50 MHz (derived from the Arty's 100 MHz oscillator via MMCM/2).
 - Reset: synchronous active-high, signal named `rst`. The Arty's `CK_RST` button
   is active-low; the top-level wraps it through a 2-FF synchronizer and inverts
   to produce the internal `rst`. The rest of the design only sees synchronous
   active-high.
-- BRAM init files: `mem/*.mem` in hex format, one 32-bit word per line.
-- Firmware source: `fw/` directory. Built with `riscv64-unknown-elf-gcc`
+- BRAM init files: `FPGA/mem/*.mem` in hex format, one 32-bit word per line.
+- Firmware source: `Software/fw/` directory. Built with `riscv64-unknown-elf-gcc`
   (multilib build required). March string evolves with the implemented ISA:
   - Phase 8 (pre-CSR bare-metal): `-march=rv32im -mabi=ilp32`
   - Phase 12+ (CSRs/Zifencei decoded): `-march=rv32im_zicsr_zifencei -mabi=ilp32`
@@ -37,18 +37,35 @@ See ROADMAP.md for the full phased plan.
 ## Directory Structure
 
 ```
-rtl/                  — synthesizable source
-  pkg/                — packages (rv32_pkg.sv)
-  core/               — CPU core modules (ALU, M unit, decoder, regfile, datapath)
-  periph/             — peripherals (UART, timer, PLIC, etc.)
-  top/                — top-level and SoC integration
-tb/                   — testbenches (tb_<module>.sv)
-mem/                  — BRAM init files (.mem)
-fw/                   — firmware source (C, assembly, linker scripts)
-constraints/          — Vivado XDC constraint files
-docs/                 — block diagrams, notes
+FPGA/                 — everything that ends up on the FPGA
+  rtl/                — synthesizable source
+    pkg/              — packages (rv32_pkg.sv)
+    core/             — CPU core modules (ALU, M unit, decoder, regfile, datapath)
+    periph/           — peripherals (UART, timer, PLIC, etc.)
+    top/              — top-level and SoC integration
+  tb/                 — testbenches (tb_<module>.sv)
+  constraints/        — Vivado XDC constraint files
+  mem/                — BRAM init files (.mem)
+  vivado/             — Vivado project workspace (regenerated, not committed)
+                        only create_project.tcl is committed; .xpr and
+                        *.runs / *.cache / *.hw / *.sim / *.gen / *.srcs /
+                        *.ip_user_files are git-ignored
+Software/             — software that runs on the CPU
+  fw/                 — bare-metal firmware, crt0, linker scripts (Phase 8+)
+  bios/               — BIOS / monitor + ELF loader (Phase 9, 10)
+  kernel/             — tiny custom kernel, later Linux artifacts (Phase 11, 19, 20)
+Docs/                 — block diagrams, architectural notes
 ```
 
+The Vivado project lives in `FPGA/vivado/`, not at the repo root. The `.xpr`
+itself is **not** committed — `create_project.tcl` is the source of truth, and
+each developer regenerates the project locally with
+`vivado -mode batch -source FPGA/vivado/create_project.tcl`. RTL and testbench
+files are added to the project as **references** to `../rtl/...` and
+`../tb/...` so the actual source of truth stays in version control. All
+generated state (`*.xpr`, `*.runs/`, `*.cache/`, `*.hw/`, `*.sim/`,
+`*.ip_user_files/`, `*.gen/`, `*.srcs/`) is git-ignored.
+
 ## ISA Target
 
 End target: **RV32IMA + Zicsr + Zifencei + M/S/U privilege + Sv32** (Linux-capable).