Add game binaries, test infrastructure, and runtime fixes

.gitignore

@@ -12,3 +12,6 @@ lib/openai/api_key.lua
 # Save game files created by tests
 *.sav
 *.tmp
+
+# Archive files
+*.zip

AGENTS.md

@@ -18,10 +18,11 @@ Start with [ARCHITECTURE.md](ARCHITECTURE.md). It is the canonical high-level su
 2. Prefer the narrowest layer that actually controls the behavior under change.
 3. For compiler issues, start in the most specific emitter or lowering module under [zilscript/compiler](zilscript/compiler).
 4. For content or gameplay issues, inspect the relevant adventure folder under [infocom](infocom) or [books](books) before changing engine code.
-5. Validate with the smallest relevant target from [Makefile](Makefile); for broad gameplay regressions, use `make test-pure-zil`.
+5. When debugging ZIL-related failures, prefer adding temporary `TELL`/print commands directly in the relevant ZIL routines to expose values, branch choices, and object locations while narrowing the problem. Remove or clearly quarantine this instrumentation before finishing unless it is intentionally part of a test.
+6. Validate with the smallest relevant target from [Makefile](Makefile); for broad gameplay regressions, use `make test-pure-zil`.
 
 ## Current Repo Notes
 
 - Imported Infocom materials are vendored as regular folders, not git submodules.
 - Skills and staged adventure-building guidance live under [skills](skills).
-- The root [ARCHITECTURE.md](ARCHITECTURE.md) file is intended to be the first-stop overview for future agent runs.
+- The root [ARCHITECTURE.md](ARCHITECTURE.md) file is intended to be the first-stop overview for future agent runs.

ARCHITECTURE.md

@@ -158,6 +158,32 @@ Recommended edit strategy:
 - Imported Infocom directories are vendored directly in the repository rather than managed as git submodules.
 - Skills and adventure-process guidance live under [skills](/Users/ICHERNA/Developer/adventure-arena/External/zilscript/skills).
 
+## Reference Documentation
+
+The [docs](/Users/ICHERNA/Developer/adventure-arena/External/zilscript/docs) directory contains reference PDFs for the ZIL language and Z-machine architecture:
+
+- [Internal_Secrets_Ko_2019.pdf](/Users/ICHERNA/Developer/adventure-arena/External/zilscript/docs/Internal_Secrets_Ko_2019.pdf): Comprehensive guide to how Infocom's ZIL language was implemented and how the Z-machine works internally. Covers object properties, dictionary format, clock/interrupt system, and memory layout.
+- [ZILF Reference Guide.pdf](/Users/ICHERNA/Developer/adventure-arena/External/zilscript/docs/ZILF%20Reference%20Guide.pdf): Modern ZILF compiler reference. Documents ZIL syntax, standard forms, compile-time evaluation (`%<COND ...>`), macros, property/flag semantics, and the DIRECTIONS/SYNTAX/OBJECT system.
+
+These documents are the authoritative references when implementing or debugging ZIL language features in the compiler and runtime.
+
+## Known Engine Constraints
+
+### Compile-time Evaluation
+
+The parser evaluates `%<COND ...>` at parse time using [zilscript/evaluate.lua](/Users/ICHERNA/Developer/adventure-arena/External/zilscript/zilscript/evaluate.lua). This currently supports `ZORK-NUMBER` checks (reading from `_G.ZORK_NUMBER` at parse time) and `GASSIGNED?` (always true). The `<SETG ZORK-NUMBER N>` at the top of a test file must execute at runtime *before* `INSERT_FILE` calls that contain compile-time conditionals.
+
+### Module Load Order
+
+Because `INSERT_FILE` parses, compiles, and executes each file sequentially at runtime, forward references between files matter:
+
+- Direction properties (`PQNORTH`, `PQSE`, etc.) are assigned when the first `ROOM` with that exit is created via `OBJECT()`. Code that references these values (like `TABLE(PQNORTH, ...)`) must load *after* the `DIRECTIONS` directive and room definitions.
+- For Zork II specifically, the `EIGHT-DIRECTIONS` table in `2actions.zil` references direction properties that don't exist until `2dungeon.zil` loads. The test file re-creates this table after all modules load as a workaround.
+
+### Clock/Interrupt System
+
+The CLOCKER in `gclock.zil` uses memory-based vectors (`C-TABLE`, `REST`, `GET`, `PUT`) to track timed events. `QUEUE(routine, ticks)` schedules an interrupt; `CLOCKER` decrements ticks each turn and fires the routine when tick reaches 1. Some game mechanics (balloon, wizard appearances) depend on interrupts firing at the right time relative to the deterministic RANDOM sequence in tests.
+
 ## Minimal Mental Model
 
 If you only need the shortest useful model for this repo, use this:

Makefile

@@ -1,5 +1,5 @@
 # Targets
-.PHONY: test test-all test-unit test-integration test-zork1 test-parser test-containers test-directions test-light test-pronouns test-take test-turnbit test-clock test-clock-direct test-assertions test-check-commands test-horror-helpers test-horror-partial test-horror test-horror-failures test-horror-all test-pure-zil test-simple-new test-insert-file test-let test-save help
+.PHONY: test test-all test-unit test-integration test-zork1 test-zork2 test-parser test-containers test-directions test-light test-pronouns test-take test-turnbit test-clock test-clock-direct test-assertions test-check-commands test-horror-helpers test-horror-partial test-horror test-horror-failures test-horror-all test-pure-zil test-simple-new test-insert-file test-let test-save help
 
 help:
 	@echo "Available targets:"
@@ -11,6 +11,7 @@ help:
 	@echo "  test-unit         - Run unit tests only"
 	@echo "  test-integration  - Run all integration tests"
 	@echo "  test-zork1        - Run Zork1 integration tests"
+	@echo "  test-zork2        - Run Zork2 integration tests"
 	@echo "  test-parser       - Run all parser/runtime tests"
 	@echo "  test-pure-zil     - Run pure ZIL tests (using ASSERT functions)"
 	@echo ""
@@ -51,13 +52,17 @@ test-unit:
 	@echo "Running unit tests..."
 	lua tests/run_all.lua
 
-test-integration: test-zork1 test-parser test-horror-all
+test-integration: test-zork1 test-zork2 test-parser test-horror-all
 	@echo "All integration tests completed!"
 
 test-zork1:
 	@echo "Running Zork1 integration tests..."
 	@lua5.4 run-zil-test.lua infocom/zork1/test/zork1-walkthrough
 
+test-zork2:
+	@echo "Running Zork2 integration tests..."
+	@lua5.4 run-zil-test.lua infocom/zork2/test/test-auto-generated
+
 test-parser: test-containers test-directions test-light test-pronouns test-take test-turnbit test-clock test-clock-direct test-assertions test-check-commands test-simple-new test-insert-file test-let test-save
 	@echo "All parser/runtime tests completed!"
 
@@ -150,4 +155,5 @@ test-pure-zil:
 	@lua5.4 run-zil-test.lua books/blackwood-horror/test/test-helpers
 	@lua5.4 run-zil-test.lua books/blackwood-horror/test/test-failures
 	@lua5.4 run-zil-test.lua infocom/zork1/test/zork1-walkthrough
+	@lua5.4 run-zil-test.lua infocom/zork2/test/test-auto-generated
 	@echo "All pure ZIL tests completed!"