Initial commit

docs/learning-roadmap.md

@@ -0,0 +1,57 @@
+# Learning roadmap
+
+## Phase 0: Zig environment and language model
+
+- Install/verify Zig and editor tooling.
+- Learn `zig build`, tests, allocators, slices, error unions, `defer`, `comptime`, and C interop.
+- Keep notes on concepts that differ from Go/Rust/C.
+
+## Phase 1: Rendering bootstrap
+
+Goal: finish the copied Vulkan/GLFW path well enough to draw and present simple 2D shapes.
+
+Learning targets:
+- Vulkan setup order and resource lifetimes.
+- Swapchain, render pass, framebuffers, command buffers, synchronization.
+- Coordinate transforms for a 2D board.
+- Frame timing and redraw strategies.
+
+## Phase 2: Chess model
+
+Learning targets:
+- Board coordinates and piece representation.
+- Move structs and game-state snapshots.
+- Rule edge cases: castling, en passant, promotion, check, checkmate, stalemate.
+- Tests for correctness before UI complexity.
+
+## Phase 3: Interactive board UI
+
+Learning targets:
+- Mapping mouse/window coordinates to squares.
+- Selection state and legal-move highlighting.
+- Separating rendering state from game rules.
+- Debug overlays for learning and testing.
+
+## Phase 4: Notation and validation
+
+Learning targets:
+- FEN import/export.
+- Algebraic notation basics.
+- Perft-style move-generation tests.
+- Golden tests and small fixtures.
+
+## Phase 5: Engine/search experiments
+
+Learning targets:
+- Evaluation functions.
+- Minimax/negamax and alpha-beta pruning.
+- Move ordering, transposition tables, and iterative deepening as later topics.
+- Deterministic benchmarks for search changes.
+
+## Phase 6: Optimization
+
+Learning targets:
+- Profiling before optimizing.
+- Board representation options: mailbox arrays, 0x88, bitboards.
+- Allocation-free move generation experiments.
+- SIMD/vectorization and cache-aware data layouts where evidence supports it.

docs/research-guidelines.md

@@ -0,0 +1,27 @@
+# Research guidelines
+
+Use these standards when asking subagents for chess algorithms, rendering, or optimization help.
+
+## Good prompts
+
+- "Compare mailbox arrays, 0x88, and bitboards for a beginner-friendly Zig chess engine; cite sources and propose experiments."
+- "Research legal move generation edge cases and perft testing for chess correctness."
+- "Review a simple Vulkan chessboard renderer for resource lifetime and data-layout risks."
+- "Explain alpha-beta pruning and move ordering with references and benchmark ideas."
+
+## Expected evidence
+
+- Official Zig documentation for Zig behavior.
+- Chess programming references, engine documentation, or reputable technical articles for chess algorithms.
+- Vulkan/GLFW upstream documentation for rendering behavior.
+- Vendor/compiler documentation for low-level optimization claims.
+
+## Required distinction
+
+Every research answer should separate:
+
+1. Established facts.
+2. Design tradeoffs.
+3. Hypotheses requiring measurement.
+4. Suggested experiments/benchmarks.
+5. References for follow-up.