backend-infra-engineer: Release v0.3.2 snapshot

assets/agent/oracle_of_secrets_guide.txt

@@ -0,0 +1,98 @@
+# Oracle of Secrets ROM Hack Expert Knowledge
+
+## Custom Memory Regions
+
+### WRAM ($7E0730-$7E078F) - 96 bytes custom
+- $7E0730: MenuScrollLevelV (menu system)
+- $7E0731: MenuScrollLevelH  
+- $7E0739: GoldstarOrHookshot (item differentiation)
+- $7E073A: Neck_Index (multi-part boss sprites)
+- $7E0741-0743: Offspring IDs (boss mechanics)
+- $7E0745: FishingOrPortalRod
+
+### SRAM Custom Variables
+- $7EF3D6: OOSPROG (main progression bitfield)
+- $7EF3C6: OOSPROG2 (secondary progression)
+- $7EF347-358: Masks (Zora, Bunny, Deku, Wolf, Stone)
+- $7EF38A-3C4: Collectibles (Bananas, Seashells, Scrolls, etc.)
+- $7EF410: Dreams (Courage/Power/Wisdom collectibles)
+
+## Custom ROM Banks
+- Bank $20 ($208000): Expanded Music
+- Bank $28 ($288000): ZSCustomOverworld data/code
+- Bank $2B ($2B8000): Items
+- Bank $2C ($2C8000): Dungeons
+- Bank $2D ($2D8000): Menu
+- Bank $30-32 ($308000+): Sprites (3 banks)
+- Bank $33-3B: Mask transformation graphics
+- Bank $40-41: Custom overworld maps (LW/DW)
+
+## Namespace Architecture
+
+### Oracle Namespace
+Most custom code in `namespace Oracle {}`:
+- Items/, Menu/, Masks/, Sprites/, Core/
+
+### ZScream (No Namespace)
+ZSCustomOverworld.asm operates outside namespace
+Hook vanilla addresses directly
+
+### Cross-Namespace Pattern
+**Oracle calling ZScream:**
+```asm
+namespace Oracle {
+  JSL Oracle_ZScreamFunction  // Use Oracle_ prefix
+}
+```
+
+**ZScream calling Oracle (bridge):**
+```asm
+ZSO_BridgeFunction:
+  JSL Oracle_OracleFunction
+  RTL
+
+namespace Oracle {
+  Oracle_ZSO_BridgeFunction = ZSO_BridgeFunction
+}
+```
+
+## ZScream Tables ($288000+)
+- BGColorTable: Background colors per screen
+- MainPaletteTable: Palette group indices
+- AnimatedTable: Animated tile GFX IDs
+- OverlayTable: Weather/effect overlays (0x9F=rain, 0xFF=none)
+- OWGFXGroupTable: 8 GFX sheets per screen
+- Overworld_ActualScreenID_New: Parent screen for 2x2 areas
+- Overworld_SpritePointers_state_X: Sprite sets per game state
+
+## Day/Night System Integration
+Oracle adds time system with 6 states:
+- State 0-2: Day (base game states)
+- State 3-5: Night (parallel states)
+- CheckIfNight16Bit: Returns state offset for night
+
+Sprite loading checks time and uses offset pointers
+
+## Processor State Safety
+**CRITICAL:** Always PHP/PLP when crossing namespaces
+ZScream uses 8-bit mode, Oracle often uses 16-bit
+Mismatch = BRK crash
+
+## Common Debugging
+**BRK Crash:** Check stack with Mesen-S, look for RTL without JSL
+**Missing Graphics:** Verify GFX slot assignment (0-6)
+**Wrong Sprites:** Check sprite pointer table for current game state
+**Palette Issues:** Day/night transition may need palette reload
+
+## Tool Usage for Oracle ROMs
+When analyzing custom features:
+1. hex-read custom WRAM ($7E0730+) to check states
+2. hex-read SRAM ($7EF3D6, $7EF410) for progression
+3. hex-search for custom sprite IDs (>0xF3 often custom)
+4. palette-analyze for day/night palette differences
+
+When editing Oracle ROMs:
+1. Check OOSPROG flags before major edits
+2. Verify namespace exports exist
+3. Test day AND night variants
+4. Ensure processor state preserved across boundaries