From 89a2df6de1f913c54699ea32158c23aa22d1927d Mon Sep 17 00:00:00 2001
From: JC-000 <3798556+JC-000@users.noreply.github.com>
Date: Fri, 14 Aug 2026 10:29:33 -0500
Subject: [PATCH] docs: restore the build prerequisites block to the README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The block added in f239e63 is absent from README.md at master — zero
mentions of `ip65-libs` or `ip65-blob`, and the `.incbin` error string
gone. A later merge dropped it. CLAUDE.md kept the content, but the
README is where a newcomer looks, and both prerequisites came from real
contributor reports (#89, #90).

Restored ahead of ## Architecture, now scoped so it does not compete
with the new "I just want to run it" section: release users skip it
entirely; it is for building from source.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README.md b/README.md
index 0847f9a..31cf286 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,31 @@ involving a C64.
 
 To build these yourself: `make package && make package-verify`.
 
+## Before you build or test
+
+Skip this if you took a release above — it is only for building from source.
+
+Two prerequisites are not vendored here, and missing either fails with an error
+that does not name it. Both are one-time, per clone:
+
+```bash
+git submodule update --init --recursive
+
+# ip65 backend only — `make` will NOT build the blob for you
+make ip65-libs
+make ip65-blob
+
+# any test script, VICE or hardware — separate public repo, not in requirements.txt
+git clone https://github.com/JC-000/c64-test-harness    # sibling of this repo
+python3 -m pip install -e ../c64-test-harness
+```
+
+Skipping the first gives `ip65_blob.s(22): Error: Cannot open include file
+'.../ip65-c64.bin'` (reported as #89); skipping the second gives
+`ModuleNotFoundError: No module named 'c64_test_harness'` (#90). Use
+`python3 -m pip` so the package lands in the interpreter that runs the scripts —
+a venv mismatch reproduces #90 exactly after an install that appeared to succeed.
+
 ## Architecture
 
 ```