feat: Centralize icon sizing and enhance AI documentation

- Add IconSizeConfig class for centralized icon dimension constants
  (ADDON_ICON_SIZE=64, INSTALLED_INDICATOR_SIZE=32)
- Update all GUI components to use IconSizeConfig instead of hardcoded sizes
  (AddonDetailScreen, BrowseAddonsScreen, InstalledAddonsScreen, WAddonCard)
- Update IconPreloadSystem to use centralized size constants for texture creation

Documentation improvements:
- Expand CLAUDE.md with project structure, architecture patterns,
  and detailed icon sizing/texture rendering documentation
- Add comprehensive GEMINI.md with project context, threading model,
  build instructions, and code search guidelines
- Add Gemini MCP server configuration (.gemini/settings.json)

This refactoring makes icon sizes configurable from a single location
and provides comprehensive guidance for AI assistants working on the codebase.

Author: GhostTypes

.gemini/settings.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "gradle-mcp-server": {
+      "command": "cmd.exe",
+      "args": [
+        "/c",
+        "cd C:\\Users\\Cope\\Documents\\GitHub\\gradle-mcp-server && npm start"
+      ]
+    },
+    "code-search-mcp": {
+      "command": "cmd.exe",
+      "args": [
+        "/c",
+        "cd C:\\Users\\Cope\\Documents\\GitHub\\code-search-mcp && node dist/index.js"
+      ]
+    }
+  }
+}

CLAUDE.md

@@ -23,6 +23,51 @@ This is a **Meteor Client addon** that provides an in-game GUI for browsing, ins
 ./gradlew clean build
 ```
 
+## Project Structure
+
+```
+src/main/java/com/cope/meteoraddons/
+├── MeteorAddonsAddon.java           # Entry point, addon initialization
+├── config/
+│   └── IconSizeConfig.java          # Centralized icon size constants
+├── systems/
+│   ├── AddonManager.java            # Core system: addon fetching, filtering, downloads
+│   └── IconPreloadSystem.java       # Icon download & GPU texture management
+├── addons/
+│   ├── Addon.java                   # Base interface for all addons
+│   ├── OnlineAddon.java             # Addon from meteor-addon-scanner API
+│   └── InstalledAddon.java          # Local addon from mods/ folder
+├── models/
+│   └── AddonMetadata.java           # JSON model for addon metadata
+├── gui/
+│   ├── tabs/
+│   │   └── AddonsTab.java           # Main tab in Meteor GUI
+│   ├── screens/
+│   │   ├── BrowseAddonsScreen.java  # Online addons browse screen
+│   │   ├── InstalledAddonsScreen.java # Installed addons screen
+│   │   └── AddonDetailScreen.java   # Detail modal for individual addon
+│   └── widgets/
+│       └── WAddonCard.java          # Grid view addon card widget
+└── util/
+    ├── IconCache.java               # Facade for instant icon lookups
+    ├── HttpClient.java              # OkHttp wrapper with fallbacks
+    ├── VersionUtil.java             # Minecraft version detection
+    └── TimeUtil.java                # Relative time formatting
+
+src/main/resources/
+├── fabric.mod.json                  # Fabric mod metadata
+└── assets/meteor-addons/
+    ├── icon.png                     # Addon icon (shown in mod menu)
+    └── installed-icon.png           # Badge overlay for installed addons
+```
+
+**Key Patterns:**
+- `config/` - Configuration constants (sizes, URLs, etc.)
+- `systems/` - Meteor Systems (singleton managers with NBT persistence)
+- `gui/` - All GUI code organized by type (tabs, screens, widgets)
+- `util/` - Utility classes with static helper methods
+- `models/` - Data classes mapping to JSON structures
+
 ## Architecture
 
 ### Threading Model (CRITICAL)
@@ -33,7 +78,7 @@ This is a **Meteor Client addon** that provides an in-game GUI for browsing, ins
 - Use `mc.execute(() -> { ... })` to schedule GUI updates back on the render thread
 - See `AddonManager.fetchAddonMetadata()` for the pattern
 
-**Icon Cache Pattern**: `IconCache` uses async texture loading - always returns immediately with a default texture, then loads the real texture in the background and triggers a UI refresh callback.
+**Icon Cache Pattern**: Icons are preloaded during startup. `IconPreloadSystem` downloads PNG bytes in background threads, then converts them to GPU textures during resource reload (render thread). `IconCache.get(addon)` returns instantly - either the cached texture or a gray placeholder.
 
 ### Systems Architecture
 
@@ -81,42 +126,67 @@ public MyWidget(GuiTheme theme, Data data) {
 
 The `theme` field is set by the framework when the widget is added to the widget tree. Never set it manually or call `init()` from the constructor.
 
+### Icon Sizing (IMPORTANT)
+
+All addon icon sizes are centralized in `IconSizeConfig.java`:
+
+```java
+public static final int ADDON_ICON_SIZE = 64;  // Change here to adjust globally
+public static final int INSTALLED_INDICATOR_SIZE = 32;
+```
+
+**All icons display at 64x64 pixels** across grid view, list view, detail screens, and installed addons. To change icon sizes:
+1. Edit `IconSizeConfig.ADDON_ICON_SIZE`
+2. Rebuild - all GUI components and texture creation automatically use the new size
+
 ### Texture Rendering
 
-For custom textures (like addon icons):
+Icon textures are managed by `IconPreloadSystem`:
 
-1. Extend `meteordevelopment.meteorclient.renderer.Texture` (NOT Minecraft's texture classes)
-2. Use `NativeImage.read()` to load images (handles any size)
-3. Resize to target dimensions using `NativeImage.resizeSubRectTo()`
-4. Convert to RGBA byte array via `makePixelArray()` and manual color conversion (ABGR → RGBA)
-5. Upload with `upload(byte[])`
+1. **Download Phase**: HTTP downloads cache raw PNG bytes (`iconDataCache`)
+2. **Resource Reload**: `reload()` converts cached PNGs to GPU textures on render thread
+3. **Texture Creation**: Uses `NativeImage.read()` → resize to `IconSizeConfig.ADDON_ICON_SIZE` → ABGR→RGBA conversion → `Texture.upload()`
+4. **Instant Lookup**: `IconCache.get(addon)` returns cached texture or default gray placeholder
 
-See `AddonIconTexture` for the complete implementation. Icons are cached at multiple sizes (64x64 for grid view, 128x128 for list view).
+See `IconPreloadSystem.createTextureFromNativeImage()` for implementation. Icons are created at a single size (64x64 by default) and used everywhere.
 
 ### Data Flow
 
-1. **Startup**: `AddonManager.init()` triggers background fetch of addons.json
-2. **Filtering**: Streams filter by MC version + verified status, deduplicate by name
-3. **Icon Caching**: IconCache loads textures asynchronously with default fallbacks
+1. **Startup**: `AddonManager.init()` triggers background fetch of addons.json and icon downloads
+2. **Icon Preload**: `IconPreloadSystem` downloads icons to byte cache, converts to textures on resource reload
+3. **Filtering**: Streams filter by MC version + verified status, deduplicate by name
 4. **GUI**: AddonsTab provides navigation to Browse/Installed screens
 5. **Details**: AddonDetailScreen modal shows full metadata + download button
 6. **Download**: `AddonManager.downloadAddon()` saves JAR to parent `mods/` folder
 
 ### Key Classes
 
+**Configuration:**
+- **IconSizeConfig**: Centralized icon size constants (`ADDON_ICON_SIZE`, `INSTALLED_INDICATOR_SIZE`)
+
+**Core Systems:**
 - **MeteorAddonsAddon**: Entry point, registers systems and tabs
 - **AddonManager**: System that manages addon state, fetching, filtering, downloading
-- **IconCache**: Async icon loading with callback-based UI refresh
+- **IconPreloadSystem**: System for async icon downloading and GPU texture creation
+- **IconCache**: Facade for instant icon texture lookups (delegates to IconPreloadSystem)
+
+**Data Models:**
 - **AddonMetadata**: JSON model with helper methods for priority fields (custom.* over regular)
+- **Addon**: Base interface for online and installed addons
+
+**GUI Screens:**
 - **AddonsTab**: Main GUI tab with navigation to Browse/Installed screens
 - **BrowseAddonsScreen**: Main screen with grid/list view of online addons
 - **InstalledAddonsScreen**: Shows locally installed Meteor addons
-- **WAddonCard**: Individual addon card widget (icon + title + button)
-- **WAddonListItem**: List view item for addons
 - **AddonDetailScreen**: Modal overlay with full addon info
-- **AddonIconTexture**: Texture implementation for resized addon icons
+
+**GUI Widgets:**
+- **WAddonCard**: Individual addon card widget for grid view (icon + title + button)
+
+**Utilities:**
 - **HttpClient**: OkHttp wrapper with fallback URL support
 - **VersionUtil**: Minecraft version detection via `SharedConstants.getGameVersion().id()`
+- **TimeUtil**: Relative time formatting for "updated 2 days ago" labels
 
 ## Version Filtering
 
@@ -145,9 +215,9 @@ The `include()` directive in build.gradle.kts bundles dependencies into the addo
 - **Fix**: Always resize images to match declared texture dimensions (e.g., 64x64)
 
 ### Icons not loading
-- **Check**: IconCache callback is set for UI refresh (`IconCache.setOnTexturesLoadedCallback()`)
-- **Check**: Network operations on background thread
-- **Check**: Texture creation on render thread via `mc.execute()`
+- **Check**: Icons downloaded during `AddonManager.fetchAddonMetadata()` background phase
+- **Check**: `IconPreloadSystem.reload()` called during resource reload to convert to textures
+- **Check**: For installed addons with JAR icons, `IconCache.get()` loads them on-demand from JAR `InputStream`
 
 ### Duplicate addons in list
 - **Fix**: Deduplication via `Collectors.toMap()` by addon name (already implemented)
@@ -211,7 +281,8 @@ The `ai_reference/` folder (git-ignored) contains complete source code for:
 - **Command implementation**: See `meteor-rejects/commands/`
 - **Event handling**: See `meteor-client/events/` and `orbit/`
 - **Settings framework**: See `meteor-client/settings/`
-- **Texture rendering**: See current `AddonIconTexture.java` implementation
+- **Texture rendering**: See `IconPreloadSystem.java` in current codebase
+- **Icon sizing**: See `IconSizeConfig.java` for centralized size constants
 
 ## Build Output
 

GEMINI.md

@@ -0,0 +1,105 @@
+# GEMINI.md - Project Context & Developer Guide
+
+This file provides comprehensive context and guidelines for Gemini agents working on the **Meteor Addons** project.
+
+## 1. Project Overview
+
+**Meteor Addons** is a specialized addon for the [Meteor Client](https://meteorclient.com/) (a Minecraft utility mod). It functions as an in-game package manager, allowing users to browse, install, and update other Meteor Client addons directly from the client's GUI.
+
+*   **Type:** Java Project (Fabric Mod / Meteor Client Addon)
+*   **Language:** Java 21
+*   **Build System:** Gradle (Kotlin DSL)
+*   **Dependencies:** Meteor Client, Fabric Loader, OkHttp, Gson
+*   **Data Source:** Fetches metadata from the [meteor-addon-scanner](https://github.com/cqb13/meteor-addon-scanner) repository.
+
+## 2. Critical Architecture & Patterns
+
+### 2.1 Threading Model (STRICT)
+*   **Render Thread:** exclusively for GUI updates and texture manipulation. **NEVER** block this thread.
+*   **Background Threads:** All network operations (HTTP requests) and heavy file I/O **MUST** run on background threads.
+    *   Use `MeteorExecutor.execute(() -> { ... })` for background tasks.
+*   **Synchronization:** To update the GUI from a background thread, schedule the task back to the render thread:
+    *   Use `mc.execute(() -> { ... })`.
+
+### 2.2 Systems Architecture
+The project uses Meteor Client's `Systems` pattern for persistent, globally accessible singletons.
+*   **Registration:** Systems are added in `MeteorAddonsAddon.onInitialize()` using `Systems.add(new MySystem())`.
+*   **Access:** `MySystem.get()` (wrapper for `Systems.get(MySystem.class)`).
+*   **Persistence:** Override `toTag()` and `fromTag()` to save/load state (NBT).
+
+### 2.3 GUI Widget Lifecycle
+Meteor's GUI framework has a strict initialization order. Violating this causes "theme is null" crashes.
+
+*   **Constructor:** Initialize data fields only. **Do NOT** build UI or call `init()`.
+*   **init():** Build your UI here. This method is called automatically by the framework *after* the widget is added to the tree and the `theme` is set.
+*   **Theme:** Access the `theme` field (provided by parent) inside `init()`. Never accept `GuiTheme` in the constructor.
+
+### 2.4 Icon Management
+*   **Centralized Config:** Icon sizes are defined in `com.cope.meteoraddons.config.IconSizeConfig`.
+    *   `ADDON_ICON_SIZE`: Default 64x64.
+*   **Preloading:** `IconPreloadSystem` handles async downloading of icon bytes.
+*   **Texture Creation:** Occurs on the render thread (via `reload()` or `mc.execute()`) using `NativeImage`.
+*   **Instant Lookup:** `IconCache` or `IconPreloadSystem.getTexture()` returns the texture immediately (or a default) to prevent rendering lag.
+
+## 3. Project Structure
+
+```
+src/main/java/com/cope/meteoraddons/
+├── MeteorAddonsAddon.java      # Main entry point. Registers systems/tabs.
+├── addons/                     # Data models
+│   ├── Addon.java              # Base interface
+│   ├── InstalledAddon.java     # Local addon wrapper (ModContainer)
+│   └── OnlineAddon.java        # Remote addon wrapper (AddonMetadata)
+├── config/
+│   └── IconSizeConfig.java     # Centralized dimension constants
+├── gui/
+│   ├── screens/                # Full-screen UIs (Browse, Installed)
+│   ├── tabs/                   # Tab integration (AddonsTab)
+│   └── widgets/                # Reusable components (WAddonCard)
+├── models/
+│   └── AddonMetadata.java      # JSON mapping for scanner data
+├── systems/
+│   ├── AddonManager.java       # Core logic: fetching, filtering, downloading
+│   └── IconPreloadSystem.java  # Async icon download & GPU texture management
+└── util/
+    ├── HttpClient.java         # OkHttp wrapper
+    └── VersionUtil.java        # Minecraft version compatibility helpers
+```
+
+## 4. Build & Execution
+
+**Mandatory:** Use the `gradle-mcp-server` tools for all build tasks. Do NOT use `run_shell_command` with `./gradlew` or `gradle`.
+
+*   **List Tasks:** `gradle_list_tasks(projectPath=...)`
+*   **Execute Task:** `gradle_execute(projectPath=..., tasks=["build"])`
+*   **Quick Build:** `gradle_build(projectPath=...)`
+*   **Project Info:** `gradle_project_info(projectPath=...)`
+*   **Dependencies:** `gradle_dependencies(projectPath=...)`
+
+## 5. Key Implementation Details
+
+*   **Data Flow:** `AddonManager.init()` -> Background Fetch -> Filter (Version/Verified) -> Deduplicate -> Async Icon Download -> Texture Creation -> GUI Render.
+*   **Networking:** Uses `OkHttp` (bundled via `include` in Gradle). Always verify internet access before assuming success.
+*   **File Operations:** Addons are downloaded to `MeteorClient.FOLDER.getParent().resolve("mods")`.
+*   **Version Filtering:** Checks `custom.supported_versions` array first, then `mc_version`.
+
+## 6. Common Pitfalls to Avoid
+1.  **Calling `init()` manually:** Never do this for Widgets.
+2.  **Blocking Render Thread:** Will freeze the game. Use `MeteorExecutor`.
+3.  **Texture Size Mismatch:** Always resize `NativeImage` to match the texture dimensions defined in `IconSizeConfig` before uploading to prevent memory violations.
+4.  **Theme Shadowing:** Do not create a `theme` field in your widget if extending a Meteor widget; use the protected field from the parent.
+
+## 7. Tools & Reference
+
+### 7.1 Code Search (Mandatory)
+Use `code-search-mcp` for all codebase exploration and navigation.
+1.  **Initialize:** Always ensure the workspace is added via `add_workspace` (if not already detected/listed).
+2.  **Search:** Prefer these tools over `grep` or basic file reading:
+    *   `search_symbols`: Find classes, methods, and variables.
+    *   `search_ast_pattern`: Find code based on structure (e.g., `Systems.add($$$)`).
+    *   `search_text`: Fast, regex-based text search (uses ripgrep).
+3.  **Investigate:** Use `codebase_investigator` for complex, high-level architectural questions.
+
+### 7.2 References
+*   **AI Reference:** The `ai_reference/` directory contains decompiled/source code of Meteor Client and other addons. Index this directory if you need to search it deeply.
+*   **Mappings:** The project uses Yarn mappings.

src/main/java/com/cope/meteoraddons/config/IconSizeConfig.java

@@ -0,0 +1,23 @@
+package com.cope.meteoraddons.config;
+
+/**
+ * Centralized configuration for icon sizes across the addon.
+ * Change these values to adjust icon sizes globally.
+ */
+public final class IconSizeConfig {
+    /**
+     * Standard addon icon size used in all GUI views.
+     * Default: 64x64 pixels
+     */
+    public static final int ADDON_ICON_SIZE = 64;
+
+    /**
+     * Installed indicator badge icon size.
+     * Default: 32x32 pixels
+     */
+    public static final int INSTALLED_INDICATOR_SIZE = 32;
+
+    private IconSizeConfig() {
+        // Prevent instantiation
+    }
+}

src/main/java/com/cope/meteoraddons/gui/screens/AddonDetailScreen.java

@@ -2,6 +2,7 @@
 
 import com.cope.meteoraddons.addons.Addon;
 import com.cope.meteoraddons.addons.OnlineAddon;
+import com.cope.meteoraddons.config.IconSizeConfig;
 import com.cope.meteoraddons.models.AddonMetadata;
 import com.cope.meteoraddons.systems.AddonManager;
 import com.cope.meteoraddons.util.IconCache;
@@ -43,7 +44,7 @@ public void initWidgets() {
 
         // Icon
         Texture iconTexture = IconCache.get(addon);
-        header.add(theme.texture(64, 64, 0, iconTexture)).widget();
+        header.add(theme.texture(IconSizeConfig.ADDON_ICON_SIZE, IconSizeConfig.ADDON_ICON_SIZE, 0, iconTexture)).widget();
 
         // Details (Name, Authors, Version, Verified)
         WVerticalList details = header.add(theme.verticalList()).expandX().widget();

src/main/java/com/cope/meteoraddons/gui/screens/BrowseAddonsScreen.java

@@ -2,6 +2,7 @@
 
 import com.cope.meteoraddons.addons.Addon;
 import com.cope.meteoraddons.addons.OnlineAddon;
+import com.cope.meteoraddons.config.IconSizeConfig;
 import com.cope.meteoraddons.gui.widgets.WAddonCard;
 import com.cope.meteoraddons.models.AddonMetadata;
 import com.cope.meteoraddons.systems.AddonManager;
@@ -101,7 +102,7 @@ private void initListView(List<Addon> addons) {
 
             // Icon
             Texture icon = IconCache.get(addon);
-            row.add(theme.texture(48, 48, 0, icon)).widget(); 
+            row.add(theme.texture(IconSizeConfig.ADDON_ICON_SIZE, IconSizeConfig.ADDON_ICON_SIZE, 0, icon)).widget(); 
 
             // Details
             WVerticalList details = row.add(theme.verticalList()).expandX().widget();

src/main/java/com/cope/meteoraddons/gui/screens/InstalledAddonsScreen.java

@@ -1,6 +1,7 @@
 package com.cope.meteoraddons.gui.screens;
 
 import com.cope.meteoraddons.addons.Addon;
+import com.cope.meteoraddons.config.IconSizeConfig;
 import com.cope.meteoraddons.systems.AddonManager;
 import com.cope.meteoraddons.util.IconCache;
 import meteordevelopment.meteorclient.gui.GuiTheme;
@@ -44,9 +45,9 @@ public void initWidgets() {
             for (int i = 0; i < addons.size(); i++) {
                 Addon addon = addons.get(i);
 
-                // Column 0: Icon (128x128)
+                // Column 0: Icon
                 Texture iconTexture = IconCache.get(addon);
-                addonList.add(theme.texture(128, 128, 0, iconTexture)).pad(8);
+                addonList.add(theme.texture(IconSizeConfig.ADDON_ICON_SIZE, IconSizeConfig.ADDON_ICON_SIZE, 0, iconTexture)).pad(8);
 
                 // Column 1: Details (expanding)
                 WVerticalList details = addonList.add(theme.verticalList()).expandCellX().widget();

src/main/java/com/cope/meteoraddons/gui/widgets/WAddonCard.java

@@ -1,6 +1,7 @@
 package com.cope.meteoraddons.gui.widgets;
 
 import com.cope.meteoraddons.addons.Addon;
+import com.cope.meteoraddons.config.IconSizeConfig;
 import com.cope.meteoraddons.util.IconCache;
 import meteordevelopment.meteorclient.gui.widgets.containers.WHorizontalList;
 import meteordevelopment.meteorclient.gui.widgets.containers.WVerticalList;
@@ -30,7 +31,7 @@ protected void onCalculateSize() {
     @Override
     public void init() {
         Texture iconTexture = IconCache.get(addon);
-        add(theme.texture(64, 64, 0, iconTexture)).centerX();
+        add(theme.texture(IconSizeConfig.ADDON_ICON_SIZE, IconSizeConfig.ADDON_ICON_SIZE, 0, iconTexture)).centerX();
 
         WHorizontalList titleRow = add(theme.horizontalList()).centerX().widget();
         titleRow.add(theme.label(addon.getName()));