Add advanced technical documentation for ZScream custom overworld

- Introduced comprehensive documentation covering internal hook architecture, memory management, graphics loading pipeline, sprite loading system, cross-namespace integration, performance considerations, and debugging strategies.
- Detailed sections on adding custom features and modifying existing behaviors, including examples and code snippets.
- Included a complete hook list and memory map quick reference for developers.

Docs/Core/MemoryMap.md

@@ -1,6 +1,56 @@
 # Memory Map
 
-This document provides a detailed map of the WRAM and SRAM memory regions, serving as a central reference for understanding the game's state.
+This document provides a detailed map of the WRAM and SRAM memory regions, serv| `$7EF358` | `WolfMask`        | Flag indicating if the player has obtained the Wolf Mask.               |
+
+### Repurposed Vanilla SRAM Blocks
+
+The following blocks were marked "unused" in vanilla ALTTP but are now utilized for OOS custom data:
+
+#### **Block $7EF38A-$7EF3C4** - Collectibles & Custom Progression
+
+*This is a large block of vanilla unused SRAM now used for various collectibles, side-quests, and tracking systems.*
+
+| Address  | Label               | Description                                                              | Verified |
+|----------|---------------------|--------------------------------------------------------------------------|----------|
+| `$7EF38A` | `FishingRod`        | Flag indicating if the player has the Fishing Rod.                       | ✓        |
+| `$7EF38B` | `Bananas`           | Number of bananas collected for side-quest.                              | ✓        |
+| `$7EF38D` | `Pineapples`        | Number of pineapples collected.                                          | ✓        |
+| `$7EF38F` | `RockMeat`          | Number of rock meat items collected.                                     | ✓        |
+| `$7EF391` | `Seashells`         | Number of secret seashells collected.                                    | ✓        |
+| `$7EF393` | `Honeycomb`         | Number of honeycombs collected.                                          | ✓        |
+| `$7EF395` | `DekuSticks`        | Number of Deku sticks collected.                                         | ✓        |
+| `$7EF396` | `TingleMaps`        | Tingle map collection tracking.                                          | ✓        |
+| `$7EF397` | `TingleId`          | Tingle identification value.                                             | ✓        |
+| `$7EF398` | `Scrolls`           | Bitfield tracking lore scroll collection (7 dungeons: `.dgi zktm`).      | ✓        |
+| `$7EF39A` | `PrevScroll`        | Tracks the previous scroll for re-reading old hints.                     | ✓        |
+| `$7EF39B` | `MagicBeanProg`     | Multi-day growth cycle tracking for magic bean side-quest (`.dts fwpb`). | ✓        |
+| `$7EF39C` | `JournalState`      | Current state of the player's journal.                                   | ✓        |
+| `$7EF39D` | `SRAM_StormsActive` | Flag indicating if the Song of Storms effect is active.                  | ✓        |
+
+#### **Block $7EF403-$7EF4FD** - Partially Repurposed
+
+*Most of this block remains unused, but OOS utilizes a portion for the Dreams collectible system.*
+
+| Address  | Label     | Description                                                        | Verified |
+|----------|-----------|--------------------------------------------------------------------|----------|
+| `$7EF410` | `Dreams`  | Bitfield tracking collection of three Dreams (`.cpw`: Courage, Power, Wisdom). | ✓        |
+
+> **💡 Usage Notes:**
+> - **Scrolls** (`$7EF398`): One scroll per dungeon (7 total). Bitfield format: `.dgi zktm` where each letter represents a dungeon (m=Mushroom Grotto, t=Tail Palace, k=Kalyxo Castle, z=Zora Temple, i=Glacia Estate, g=Goron Mines, d=Dragon Ship).
+> - **MagicBeanProg** (`$7EF39B`): Tracks multi-day growth cycle with bitfield `.dts fwpb` (b=bean planted, w=watered, p=pollinated, f=first day, s=second day, t=third day, d=done).
+> - **Dreams** (`$7EF410`): Similar to vanilla Pendants, tracks three key collectibles. Bitfield: `.cpw` (c=Courage, p=Power, w=Wisdom).
+
+### SRAM Address Contradictions (Source File Notes)
+
+The following addresses appear with both active label definitions and `UNUSED_` markers in `Core/sram.asm`. **The label definitions take precedence** - these addresses are actively used:
+
+- `$7EF3D4` - Both `MakuTreeQuest` and `UNUSED_7EF3D4` (✓ **In Use**)
+- `$7EF3D6` - Both `OOSPROG` and `UNUSED_7EF3D6` (✓ **In Use**)
+- `$7EF38A` - Both `FishingRod` and `UNUSED_7EF38A` (✓ **In Use**)
+
+These contradictions appear to be legacy comments from the vanilla ALTTP disassembly that were not removed when OOS repurposed these addresses.
+
+ as a central reference for understanding the game's state.
 
 ## 1. WRAM (Work RAM) - `$7E0000`
 
@@ -48,6 +98,8 @@ This section details the layout of the game's volatile memory.
 
 This section details the layout of the save file memory.
 
+> **🔍 SRAM Verification Note**: All custom SRAM variables documented below have been cross-referenced with `Core/sram.asm`. Some addresses in the source file have contradictory `UNUSED_` markers alongside actual label definitions (e.g., `OOSPROG = $7EF3D6` vs `UNUSED_7EF3D6 = $7EF3D6`). **The actual usage takes precedence** - if a label is defined for an address, it is considered in-use regardless of `UNUSED_` markers. This appears to be a legacy comment artifact from the vanilla ALTTP disassembly.
+
 ### Key Vanilla SRAM Variables
 
 *This section lists key vanilla save data locations, such as inventory, health, and progression flags, as defined in `Core/sram.asm`.*

Docs/Core/Ram.md

@@ -48,6 +48,44 @@ Once a room is loaded, its specific behavior is governed by tags and flags.
 
     The sprite engine in `bank_06.asm` iterates through these arrays each frame, executing the logic for each active sprite.
 
+## 4.5. Custom WRAM Region (`$7E0730+`)
+
+Oracle of Secrets adds a custom WRAM region starting at `$7E0730`, utilizing the MAP16OVERFLOW free RAM space. All custom variables documented here have been verified against `Core/ram.asm` and are actively used by the project's custom systems.
+
+### Verified Custom WRAM Variables
+
+| Address    | Label                   | Description                                               | Verified |
+|------------|-------------------------|-----------------------------------------------------------|----------|
+| `$7E0730`  | `MenuScrollLevelV`      | Vertical scroll position for the custom menu system       | ✓        |
+| `$7E0731`  | `MenuScrollLevelH`      | Horizontal scroll position for the custom menu system     | ✓        |
+| `$7E0732`  | `MenuScrollHDirection`  | Direction flag for horizontal menu scrolling (2 bytes)    | ✓        |
+| `$7E0734`  | `MenuItemValueSpoof`    | Temporary override for displayed menu item values (2 bytes)| ✓       |
+| `$7E0736`  | `ShortSpoof`            | Shorter version of the spoof value (1 byte)               | ✓        |
+| `$7E0737`  | `MusicNoteValue`        | Current music note value for Ocarina system (2 bytes)     | ✓        |
+| `$7E0739`  | `GoldstarOrHookshot`    | Differentiates Hookshot (0) from Goldstar (1) mode        | ✓        |
+| `$7E073A`  | `Neck_Index`            | Index for multi-part sprite body tracking (e.g., bosses)  | ✓        |
+| `$7E073B`  | `Neck1_OffsetX`         | X-offset for first neck/body segment                      | ✓        |
+| `$7E073C`  | `Neck1_OffsetY`         | Y-offset for first neck/body segment                      | ✓        |
+| `$7E073D`  | `Neck2_OffsetX`         | X-offset for second neck/body segment                     | ✓        |
+| `$7E073E`  | `Neck2_OffsetY`         | Y-offset for second neck/body segment                     | ✓        |
+| `$7E073F`  | `Neck3_OffsetX`         | X-offset for third neck/body segment                      | ✓        |
+| `$7E0740`  | `Neck3_OffsetY`         | Y-offset for third neck/body segment                      | ✓        |
+| `$7E0741`  | `Offspring1_Id`         | Sprite ID of first child sprite (for boss mechanics)      | ✓        |
+| `$7E0742`  | `Offspring2_Id`         | Sprite ID of second child sprite (for boss mechanics)     | ✓        |
+| `$7E0743`  | `Offspring3_Id`         | Sprite ID of third child sprite (for boss mechanics)      | ✓        |
+| `$7E0744`  | `Kydreeok_Id`           | Sprite ID for Kydreeok boss entity                        | ✓        |
+| `$7E0745`  | `FishingOrPortalRod`    | Differentiates Fishing Rod (1) from Portal Rod (2)        | ✓        |
+
+### Usage Notes
+
+-   **Menu System**: Variables `$7E0730-$7E0736` are exclusively used by the custom menu system (`Menu/menu.asm`) to manage smooth scrolling between the Items and Quest Status pages.
+
+-   **Item Differentiation**: `GoldstarOrHookshot` and `FishingOrPortalRod` are critical for shared inventory slots. These allow two distinct items to occupy a single menu slot, with the player able to switch between them using the L/R shoulder buttons.
+
+-   **Boss Mechanics**: The `Neck_*` and `Offspring_*` variables enable complex multi-part boss sprites (e.g., Kydreeok with multiple heads, Manhandla with independent parts). The parent sprite uses these to track and coordinate its child sprite components.
+
+-   **Memory Safety**: All variables in this region are placed within the MAP16OVERFLOW free RAM area, which is guaranteed to be unused by the vanilla game engine. This prevents conflicts with vanilla systems.
+
 ## 5. Long-Term Progression: SRAM and Custom Flags
 
 SRAM (`$7EF000+`) stores the player's save file and is the key to managing long-term quest progression. Oracle of Secrets heavily expands the vanilla save format to support its new data-driven systems.