diff --git a/GEMINI.md b/GEMINI.md
new file mode 100644
index 0000000..7679e5d
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1,49 @@
+# GitHub Repository
+https://github.com/ToontownSuperForeverMVP/TOONTOWN-BEST-THE-NEW-.git
+
+# Project Overview
+This repository contains **Toontown Super Forever MVP** (TOONTOWN-BEST-THE-NEW-), an open-source Toontown server and client codebase powered by Panda3D and Astron.
+
+# Codebase Architecture & Structure
+- **`toontown/`**: Main Toontown client logic, including game states, hoods, quest systems, shaders, GUI, and base files.
+  - `toontown/hood/`: Outdoor lighting and procedural sky features.
+  - `toontown/launcher/`: Local server management, launcher routines, user options.
+  - `toontown/quest/`: Quest automation, `AutoerManager`, `TaskAutoer`.
+  - `toontown/safezone/`: Crane sandboxes (`DistributedTTCCraneSandbox`, AI variant).
+  - `toontown/shaders/`: Custom visual shaders (water, sky, sunrays).
+  - `toontown/shtiker/`: Custom Shtiker Book pages (`AutoerPage`).
+  - `toontown/toontowngui/`: Modern loading screens (`ModernLoadingScreen`, `LoadingAssetPreview`, `ZonePrefetchCatalog`, `ToontownLoadingScreen`).
+- **`otp/`**: Online Toontown Protocol framework (common networking, avatar, chat, and distributed object classes).
+- **`astron/`**: Server backend configuration, cluster definitions, and database schemas.
+- **`autoers/`**: Bot scripts and quest automation modules.
+- **`tools/`**: Development, maintenance, and asset management scripts.
+- **`win32/`, `linux/`, `darwin/`**: Engine launcher scripts and platform-specific binaries/tools.
+
+# Git Status Analysis
+- **Current Working Branch**: `feature/modern-loading-system`
+- **Tracked & Staged Features**:
+  - Full Modern Loading System (`ModernLoadingScreen.py`, `LoadingAssetPreview.py`, `ZonePrefetchCatalog.py`)
+  - Integration with `ToontownLoader.py`, `ToontownLoadingScreen.py`, and `AssetCache.py`
+
+# Open Pull Requests
+- **PR #9**: `UI & Performance: Full modern loading system with 3D asset preview and async prefetching` (`feature/modern-loading-system`)
+- **PR #7**: `Core: Codebase fixes, Astron compatibility, and widescreen offsets` (`feature/core-codebase-fixes`)
+- **PR #6**: `Automation: Add bot scripts, quest autoers, and custom shtiker page` (`feature/automation-bots`)
+- **PR #5**: `Graphics: Custom shaders (water, sky, sunrays) and outdoor lighting` (`feature/graphics-shaders`)
+- **PR #4**: `Performance: Add animation interpolation, async prefetch, and event flood prevention` (`feature/performance-optimizations`)
+- **PR #3**: `GUI: Add Modern Loading Screen and Asset Preview Overlay` (`feature/modern-loading-screen`)
+- **PR #2**: `Launcher: Improve Windows startup scripts and add LocalServerManager` (`feature/launcher-and-servers`)
+- **PR #1**: `Update from task f885637e-e2a0-4db6-b2cf-e8297682242a` (`optimizing-guis-for-widescreen-2242a`)
+
+# Completed Work
+- [x] Implemented `ModernLoadingScreen.py`: Full-screen launcher/game load screen with animated gradient background, pulsing lighting, progress bar, asset captions, tip dict support, and smooth outro fade sequence.
+- [x] Implemented `LoadingAssetPreview.py`: Live 3D asset preview card rendering models, textures, fonts, and audio in an offscreen Panda3D buffer without interfering with main render world.
+- [x] Implemented `ZonePrefetchCatalog.py`: Catalog mapping all hood zone IDs (TTC, DD, DG, MML, TB, DD, Speedway, Cog HQs, Estate) with async background preloading (`ZonePrefetchManager`).
+- [x] Integrated `ToontownLoader.py` & `ToontownLoadingScreen.py`: Automatic asset callback forwarding, heartbeat keepalive, and fallback support.
+- [x] Expanded `AssetCache.py`: Instant preloading of common Phase 3, 3.5, 4, 5 GUI models, chatboxes, shadows, and logos.
+- [x] Submitted Pull Request #9 to GitHub repository (`feature/modern-loading-system`).
+
+# TODO List for Future AI Instances
+- [ ] Merge and review PR #9 into `develop`.
+- [ ] Validate server stability with Astron local launcher under heavy zone switching.
+- [ ] Test full client load times across low-end and high-end configurations.