Document build issues found during README testing

- Critical compilation error: direct access to internal ncurses structure members
- Code compatibility issue with modern ncurses (curscr->_cury, curscr->_curx)
- Affects both standard and manual build methods
- Documented on macOS (darwin 25.0.0, Apple Silicon)

BUILD_ISSUES.md

@@ -0,0 +1,125 @@
+# Build Issues Found During README Testing
+
+This document lists issues encountered when following the README.md build instructions on macOS (darwin 25.0.0, Apple Silicon).
+
+## Date
+Testing performed: Following README.md Quick Start instructions
+
+## Environment
+- **OS**: macOS (darwin 25.0.0)
+- **Architecture**: Apple Silicon (arm64)
+- **Compiler**: GCC/Clang (available)
+- **make**: Available
+- **ncurses**: Installed via Homebrew at `/opt/homebrew/opt/ncurses`
+
+## Issues Found
+
+### 1. Compilation Error: Incomplete Type 'WINDOW'
+
+**Location**: `main.c:241-242`
+
+**Error Message**:
+```
+main.c:241:11: error: incomplete definition of type 'WINDOW' (aka 'struct _win_st')
+  241 |     curscr->_cury = oy;
+      |     ~~~~~~^
+main.c:242:11: error: incomplete definition of type 'WINDOW' (aka 'struct _win_st')
+  242 |     curscr->_curx = ox;
+      |     ~~~~~~^
+```
+
+**Root Cause**:
+The code attempts to access internal ncurses structure members (`curscr->_cury` and `curscr->_curx`) which are not part of the public API in modern ncurses libraries. These internal members are not accessible in both the system ncurses and Homebrew ncurses.
+
+**Context**:
+The problematic code is in the `tstp()` function (lines 241-242), which handles stop/start signals (SIGTSTP). After resuming from a stop signal, the code tries to manually restore the cursor position by directly accessing internal ncurses structure members.
+
+**Affected Code**:
+```c
+void
+tstp(int ignored)
+{
+    // ... code ...
+    getyx(curscr, y, x);
+    mvcur(y, x, oy, ox);
+    fflush(stdout);
+    curscr->_cury = oy;  // ERROR: Internal member access
+    curscr->_curx = ox;  // ERROR: Internal member access
+}
+```
+
+**Impact**:
+- **Severity**: CRITICAL - Build fails completely
+- The game cannot be compiled on modern systems with standard ncurses
+- This affects all platforms using modern ncurses (not just macOS)
+
+**Suggested Fix**:
+1. Remove the direct structure member access (lines 241-242)
+2. The `mvcur()` call on line 239 should be sufficient for cursor positioning
+3. If cursor position tracking is needed, use public ncurses API functions like `getyx()` and `move()` instead
+
+**Workaround Attempted**:
+- Tried using Homebrew ncurses with explicit include/library paths as suggested in README troubleshooting section
+- Same error occurred with both system ncurses and Homebrew ncurses
+- Tried manual build using `Makefile.std` as documented in README (Alternative build method)
+- Same error occurred with manual build method
+- This confirms it's a code compatibility issue, not a configuration or build system issue
+
+### 2. Compiler Warnings (Non-blocking)
+
+**Location**: Multiple files
+
+**Warning Messages**:
+- `main.c`: Multiple warnings about deprecated function prototypes (C23 compatibility)
+- Function declarations without prototypes in `extern.h` conflicting with definitions
+
+**Impact**:
+- **Severity**: LOW - Warnings only, do not prevent compilation
+- Code compiles but may have issues with future C standards (C23)
+
+**Note**: These warnings are expected for legacy C code and don't prevent the build from succeeding once the critical error is fixed.
+
+## What Works
+
+1. ✅ **Configure script**: Runs successfully
+   - Detects compiler, headers, and libraries correctly
+   - Creates `config.h` and `Makefile` properly
+   - Works with both system ncurses and Homebrew ncurses paths
+
+2. ✅ **Prerequisites**: All required tools are available
+   - C compiler (gcc/clang)
+   - make
+   - ncurses library (via Homebrew)
+
+3. ✅ **Build system**: Autotools configuration works correctly
+   - `configure` script exists and is executable
+   - No need for `autoreconf` (as documented in README)
+
+## Recommendations for README Updates
+
+1. **Add Known Compatibility Issue Section**:
+   - Document that the codebase has compatibility issues with modern ncurses
+   - Note that direct access to internal ncurses structures (`curscr->_cury`, `curscr->_curx`) will fail on modern systems
+   - Provide information about which ncurses versions are known to work (if any)
+
+2. **Update macOS Troubleshooting**:
+   - The current macOS troubleshooting section mentions Homebrew ncurses paths, but this doesn't solve the compilation error
+   - Add a note that even with correct ncurses paths, the build may fail due to code compatibility issues
+
+3. **Add Build Status**:
+   - Consider adding a "Known Issues" or "Build Status" section to the README
+   - Indicate that the codebase may need patches for modern ncurses compatibility
+
+## Next Steps
+
+1. **Code Fix Required**: The `main.c` file needs to be updated to remove direct access to internal ncurses structure members
+2. **Testing**: After fix, verify the game builds and runs correctly
+3. **Documentation**: Update README with any workarounds or fixes applied
+
+## Additional Notes
+
+- The README's Quick Start instructions are clear and easy to follow
+- The build system (Autotools) is properly configured
+- The issue is specifically with code compatibility, not with the build system or documentation
+- This appears to be a known issue with porting old curses-based code to modern ncurses
+