### Build Full Distribution with Installer

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/development.md

Builds the full distribution package, including compiling the Inno Setup installer. The output is placed in the installer_output/ directory.

```bash
python scripts/build_installer.py
```

--------------------------------

### First-Time Setup Steps

Source: https://github.com/anneardysa/ardysamodstools/blob/main/README.md

Follow these steps for the initial setup of ArdysaModsTools. Running as administrator is recommended.

```bash
1. Close Dota 2 (if running)
2. Launch ArdysaModsTools (run as Administrator recommended)
3. The app will auto-detect your Dota 2 installation folder
4. Click "Install ModsPack" to download and apply all mods
5. Start Dota 2 and enjoy your new cosmetics!
```

--------------------------------

### Install WebView2 Runtime

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/TROUBLESHOOTING.md

Install the WebView2 runtime from Microsoft to resolve errors indicating it's not found.

```bash
# Install from Microsoft
# https://developer.microsoft.com/microsoft-edge/webview2/
```

--------------------------------

### Show User Guide

Source: https://github.com/anneardysa/ardysamodstools/blob/main/Assets/Html/settings_form.html

Sends a message to the backend to display the user guide. This is typically triggered by a button click or menu item.

```javascript
function showGuide() {
  sendMessage({ type: "showGuide" });
}
```

--------------------------------

### Clone Repository for Setup

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/CONTRIBUTING.md

Cloning the ArdysaModsTools repository as part of the initial setup process.

```bash
git clone https://github.com/Anneardysa/ArdysaModsTools.git
cd ArdysaModsTools
```

--------------------------------

### Install Mods Workflow

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/user/QUICK_START.md

Follow these steps to install mods using the Auto Install feature.

```text
Main Window → Install → Auto Install → Done
```

--------------------------------

### Setup Services

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/conflict-resolution/SKILL.md

Instantiate the necessary services for conflict detection, resolution, and priority management.

```csharp
var detector = serviceProvider.GetRequiredService<IConflictDetector>();
var resolver = serviceProvider.GetRequiredService<IConflictResolver>();
var priorityService = serviceProvider.GetRequiredService<IModPriorityService>();
```

--------------------------------

### Install .NET 8 SDK

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/TROUBLESHOOTING.md

Download and install the .NET 8 SDK to resolve build errors related to missing SDKs.

```bash
# Download and install from
# https://dotnet.microsoft.com/download/dotnet/8.0
```

--------------------------------

### Install Custom Music Pack Workflow

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/custom-mod-integration/SKILL.md

End-to-end C# workflow for installing a custom music pack, including validation, installation, logging, priority setting, and verification.

```csharp
public async Task InstallCustomMusicPack(string dotaPath, string musicPackPath, CancellationToken ct)
{
    var installer = serviceProvider.GetRequiredService<IModInstallerService>();
    var priorityService = serviceProvider.GetRequiredService<IModPriorityService>();
    var activeMods = serviceProvider.GetRequiredService<IActiveModsService>();

    // 1. Validate VPK
    if (!await installer.ValidateVpkAsync(musicPackPath, ct))
        throw new InvalidOperationException("Invalid VPK file");

    // 2. Install VPK
    var result = await installer.ManualInstallModsAsync(dotaPath, musicPackPath, ct);
    if (!result.Success)
        throw new Exception($"Install failed: {result.Message}");

    // 3. Register in extraction log
    var log = MiscExtractionLog.Load(dotaPath) ?? new MiscExtractionLog();
    log.Selections["Music"] = "Custom Music Pack";
    log.Mode = "AddToCurrent";
    log.GeneratedAt = DateTime.UtcNow;
    log.AddFiles("Music", new[]
    {
        "sounds/music/custom_battle.vsnd_c",
        "sounds/music/custom_menu.vsnd_c",
        "sounds/music/custom_victory.vsnd_c"
    });
    log.Save(dotaPath);

    // 4. Set priority
    await priorityService.SetModPriorityAsync(
        "Music_Custom", "Custom Music Pack", "Music", 10, dotaPath, ct);

    // 5. Verify
    var info = await activeMods.GetActiveModsAsync(dotaPath);
    var musicMod = info.MiscMods.FirstOrDefault(m => m.Category == "Music");
    Console.WriteLine(musicMod != null
        ? $"✅ Music pack active: {musicMod.SelectedChoice}"
        : "❌ Music pack not detected");
}
```

--------------------------------

### Install Mods

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/install-mods/SKILL.md

Downloads mods from a CDN with fallback, validates the VPK, and applies patches. Use this for standard mod installation.

```csharp
var result = await installer.InstallModsAsync(dotaPath, force: false, ct);

if (result.Success)
    Console.WriteLine("Mods installed successfully");
else
    Console.WriteLine($"Failed: {result.Message}");
```

--------------------------------

### Setup and Contribution Workflow

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/README.md

Follow these steps to fork the repository, set up your local environment, make changes, and submit a pull request.

```bash
# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/ArdysaModsTools.git
cd ArdysaModsTools

# 2. Create feature branch
git checkout -b feature/amazing-feature

# 3. Setup environment
cp .env.example .env
dotnet restore

# 4. Make changes and test
dotnet build
dotnet test

# 5. Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# 6. Open Pull Request

```

--------------------------------

### Configure Environment Variables

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/CONTRIBUTING.md

Copying the example environment file and instructions to edit it with necessary configuration details.

```bash
# Copy the example environment file
cp .env.example .env

# Edit .env and fill in your configuration
# You need your own mod repository for full functionality
```

--------------------------------

### Install Custom Mod VPK

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/custom-mod-integration/SKILL.md

Install a user-provided VPK file into the game directory. This method is used for manual installations.

```csharp
var result = await installer.ManualInstallModsAsync(dotaPath, userVpkPath, ct);
if (result.Success)
    Console.WriteLine("Custom mod installed!");
else
    Console.WriteLine($"Failed: {result.Message}");
```

--------------------------------

### Install and Update Mods

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/services.md

Demonstrates how to use the ModInstallerService to install mods and update game patches. Ensure the service provider is configured to resolve IModInstallerService.

```csharp
var installer = serviceProvider.GetRequiredService<ModInstallerService>();

// Install mods
var result = await installer.InstallModsAsync(dotaPath, force: false, ct);
if (!result.Success)
{
    Console.WriteLine($"Install failed: {result.Message}");
    return;
}

// After game update - always does full patch
await installer.UpdatePatcherAsync(dotaPath,
    msg => Console.WriteLine(msg), ct);
```

--------------------------------

### Build Installer

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/INSTALLER.md

Execute the Python script to build the ArdysaModsTools installer. The output will be placed in the installer_output directory.

```powershell
python scripts\build\build_installer.py
```

--------------------------------

### Update Installer Version

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/INSTALLER.md

Modify the Inno Setup script to update the application version. This is typically done on line 9 of the installer.iss file.

```iss
#define MyAppVersion "2.0"
```

--------------------------------

### Logging Examples

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/architecture.md

Demonstrates the usage of the injected `Logger` for general logging and the static `FallbackLogger` for critical error paths.

```csharp
// Normal logging
_logger.Log("Starting installation...");
_logger.Log($"[VPK_001] Extraction failed: {ex.Message}");

// Fallback for critical paths
FallbackLogger.Log($"UnhandledException: {ex}");
```

--------------------------------

### Setup HeroGenerationService

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/generate-hero-cosmetics/SKILL.md

Obtain an instance of IHeroGenerationService using dependency injection.

```csharp
var heroGen = serviceProvider.GetRequiredService<IHeroGenerationService>();
```

--------------------------------

### Path Manipulation for Dota 2

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/helpers.md

Provides utilities for manipulating paths specific to Dota 2 installations, including normalizing target paths, getting VPK paths, and managing the mods folder. Also includes a function to ensure directories exist.

```csharp
string dotaPath = PathUtility.NormalizeTargetPath(userPath);
// "C:\Steam\steamapps\common\dota 2 beta\game\dota"

string vpkPath = PathUtility.GetVpkPath(dotaPath);
// "C:\...\game\dota\pak01_dir.vpk"

string modsFolder = PathUtility.GetModsFolder(dotaPath);
// "C:\...\game\dota\_ArdysaMods"
```

--------------------------------

### Dependency Injection Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/README.md

Demonstrates how to use IMainFormFactory for proper dependency injection in the application's entry point.

```csharp
// Program.cs uses IMainFormFactory for proper DI
var factory = serviceProvider.GetRequiredService<IMainFormFactory>();
Application.Run(factory.Create());
```

--------------------------------

### Manual Install User VPK

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/install-mods/SKILL.md

Installs a VPK file that has been provided directly by the user. This is useful for installing mods from sources other than the automated CDN download.

```csharp
var result = await installer.ManualInstallModsAsync(dotaPath, userVpkPath, ct);
```

--------------------------------

### Install Hero Skins

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/user/README.md

Follow these steps to install custom hero cosmetic sets using the Skin Selector feature.

```plaintext
Skin Selector → Select Hero → Choose Set → Install → Patch
```

--------------------------------

### Priority Config File Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/conflict-resolution/SKILL.md

An example JSON structure for the mod priority configuration file, showing last modified timestamp, mod priorities with categories and lock status, default strategy, auto-resolve settings, and category-specific strategies.

```json
{
   "lastModified": "2026-02-14T12:00:00Z",
   "priorities": [
      {
         "modId": "Weather_Rain",
         "modName": "Rain",
         "category": "Weather",
         "priority": 10,
         "isLocked": false
      },
      {
         "modId": "Weather_Snow",
         "modName": "Snow",
         "category": "Weather",
         "priority": 20,
         "isLocked": false
      }
   ],
   "defaultStrategy": 0,
   "autoResolveNonBreaking": true,
   "categoryStrategies": { "Weather": 2, "River": 2 }
}
```

--------------------------------

### KeyValues Multi-line Format Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/helpers.md

Illustrates the multi-line format for KeyValues data, commonly used for structured configuration.

```plaintext
"555"
{
    "name"       "Item Name"
    "prefab"     "wearable"
    "used_by_heroes"
    {
        "npc_dota_hero_antimage"    "1"
    }
}

```

--------------------------------

### Get All Current Settings

Source: https://github.com/anneardysa/ardysamodstools/blob/main/Assets/Html/dota2_performance.html

Returns all current settings as a JSON string.

```javascript
function getAllSettings() {
    return JSON.stringify(currentValues);
}
```

--------------------------------

### Setup IActiveModsService

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/query-active-mods/SKILL.md

Obtain an instance of IActiveModsService from the service provider. This is required before you can query any mod information.

```csharp
var activeMods = serviceProvider.GetRequiredService<IActiveModsService>();
```

--------------------------------

### Manual Dota 2 Path Selection

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/user/QUICK_START.md

If automatic detection fails, manually specify the Dota 2 installation directory.

```text
C:\Program Files (x86)\Steam\steamapps\common\dota 2 beta
```

--------------------------------

### KeyValues One-liner Format Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/helpers.md

Demonstrates the compact one-liner format for KeyValues data, which is parsed transparently by the helper functions.

```plaintext
"555"{"name""Item Name""prefab""wearable""used_by_heroes"{"npc_dota_hero_antimage""1"}}

```

--------------------------------

### Get Only Hero Mods

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/query-active-mods/SKILL.md

Retrieves a list containing only the installed hero cosmetic sets.

```APIDOC
## Get Active Hero Mods

### Description
Retrieves a list containing only the installed hero cosmetic sets.

### Method
```csharp
IReadOnlyList<ActiveHeroMod> heroes = await activeMods.GetActiveHeroModsAsync(dotaPath);
```

### Response
#### Success Response (IReadOnlyList<ActiveHeroMod>)
- A list of `ActiveHeroMod` objects, each representing an installed hero cosmetic set.
  - **HeroId** (string) - The hero's unique identifier.
  - **SetName** (string) - The name of the installed cosmetic set.
  - **InstalledFiles** (IReadOnlyList<string>) - A list of file paths associated with the mod.

### Example Usage
```csharp
IReadOnlyList<ActiveHeroMod> heroes = await activeMods.GetActiveHeroModsAsync(dotaPath);
```
```

--------------------------------

### HeroModel JSON Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/models.md

Illustrates the expected JSON structure for a HeroModel, including its properties like item IDs, names, attributes, and sets.

```json
{
   "id": [555, 556, 557],
   "name": "antimage",
   "used_by_heroes": "npc_dota_hero_antimage",
   "localized_name": "Anti-Mage",
   "primary_attr": "agility",
   "sets": {
      "Default": [],
      "Mage Slayer": ["https://cdn.example.com/sets/am_mageslayer.zip"]
   }
}
```

--------------------------------

### Get Active Categories

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/query-active-mods/SKILL.md

Retrieves a list of distinct categories for which active mods are installed.

```APIDOC
## Get Active Categories

### Description
Retrieves a list of distinct categories for which active mods are installed.

### Method
```csharp
IReadOnlyList<string> categories = info.GetActiveCategories();
```

### Response
#### Success Response (IReadOnlyList<string>)
- A list of strings, where each string is a unique category name (e.g., "Hero", "Weather", "HUD", "Terrain").

### Example Usage
```csharp
// Returns: ["Hero", "Weather", "HUD", "Terrain"]
IReadOnlyList<string> categories = info.GetActiveCategories();
```
```

--------------------------------

### Demo: Load Options, Set Version, Show Progress, and Append Console Logs

Source: https://github.com/anneardysa/ardysamodstools/blob/main/Assets/Html/misc_form.html

Demonstrates loading options, setting a version number, showing a progress indicator, and appending messages to a console log. This is for testing and simulation purposes when not running in the host environment.

```javascript
// Demo
if (!window.chrome?.webview) {
    setTimeout(() => {
        loadOptions([
            {
                id: "weather",
                name: "Weather Effects",
                thumbnailPattern: "",
                choices: [
                    { id: "default", name: "Default" },
                    { id: "rain", name: "Rain" },
                    { id: "snow", name: "Snow" },
                ],
            },
            {
                id: "terrain",
                name: "Terrain Style",
                thumbnailPattern: "",
                choices: [
                    { id: "default", name: "Default" },
                    { id: "desert", name: "Desert" },
                    { id: "immortal", name: "Immortal Gardens" },
                ],
            },
            {
                id: "announcer",
                name: "Announcer Pack",
                thumbnailPattern: "",
                choices: [
                    { id: "default", name: "Default" },
                    { id: "bastion", name: "Bastion" },
                    { id: "glados", name: "GLaDOS" },
                ],
            },
        ]);
        setVersion("2.0.16-beta"); // Test
        setTimeout(() => {
            showProgress("Testing...");
            appendConsole("Console test line 1");
            appendConsole("Console test line 2");
        }, 1000);
    }, 300);
}
```

--------------------------------

### Get Only Misc Mods

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/query-active-mods/SKILL.md

Retrieves a list containing only the installed miscellaneous mods (weather, HUD, terrain).

```APIDOC
## Get Active Misc Mods

### Description
Retrieves a list containing only the installed miscellaneous mods (weather, HUD, terrain).

### Method
```csharp
IReadOnlyList<ActiveMiscMod> misc = await activeMods.GetActiveMiscModsAsync(dotaPath);
```

### Response
#### Success Response (IReadOnlyList<ActiveMiscMod>)
- A list of `ActiveMiscMod` objects, each representing an installed miscellaneous mod.
  - **Category** (string) - The category of the mod.
  - **SelectedChoice** (string) - The specific choice selected within the category.
  - **InstalledFiles** (IReadOnlyList<string>) - A list of file paths associated with the mod.

### Example Usage
```csharp
IReadOnlyList<ActiveMiscMod> misc = await activeMods.GetActiveMiscModsAsync(dotaPath);
```
```

--------------------------------

### Get Detailed Mod Status

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/check-mod-status/SKILL.md

Performs comprehensive validation including Dota path, installed mods, gameinfo patching, signature patching, and version check. Use this to get a full picture of the mod's state.

```csharp
var status = await statusService.GetDetailedStatusAsync(dotaPath, ct);

Console.WriteLine($"Status: {status.Status}");         // Ready, NeedUpdate, NotInstalled, etc.
Console.WriteLine($"Text: {status.StatusText}");        // Human-readable status
Console.WriteLine($"Description: {status.Description}");
Console.WriteLine($"Action: {status.Action}");          // None, Install, Update, Enable, Fix
Console.WriteLine($"Button: {status.ActionButtonText}");// "Patch Update", "Install ModsPack"
Console.WriteLine($"Version: {status.Version}");
Console.WriteLine($"Color: {status.UIColor}");          // For UI display
```

--------------------------------

### Quick Start: Build and Run ArdysaModsTools

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/README.md

Clone the repository, restore dependencies, build the project in debug mode, and run the application. Includes commands for running tests.

```bash
# Clone and setup
git clone https://github.com/Anneardysa/ArdysaModsTools.git
cd ArdysaModsTools

# Build and run
dotnet restore
dotnet build -c Debug
dotnet run

# Run tests
dotnet test Tests/ArdysaModsTools.Tests.csproj
```

--------------------------------

### Get Active Categories

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/query-active-mods/SKILL.md

Obtain a list of distinct categories that have active mods installed. This is useful for understanding the types of mods currently in use.

```csharp
IReadOnlyList<string> categories = info.GetActiveCategories();
// Returns: ["Hero", "Weather", "HUD", "Terrain"]
```

--------------------------------

### Get All Active Mods

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/query-active-mods/SKILL.md

Retrieve a comprehensive snapshot of all installed mods, including hero sets and miscellaneous items. This method provides an overview of the mod status and details for each category.

```csharp
ActiveModInfo info = await activeMods.GetActiveModsAsync(dotaPath);

Console.WriteLine($"Total mods: {info.TotalModCount}");
Console.WriteLine($"Status: {info.OverallStatus}");   // Ready, NotInstalled, Error
Console.WriteLine($"Has mods: {info.HasActiveMods}");
Console.WriteLine($"Generated: {info.LastGeneratedAt}");

// List hero cosmetic sets
foreach (var hero in info.HeroMods)
    Console.WriteLine($"  Hero: {hero.HeroId} -> {hero.SetName} ({hero.InstalledFiles.Count} files)");

// List misc mods (weather, HUD, terrain)
foreach (var misc in info.MiscMods)
    Console.WriteLine($"  {misc.Category}: {misc.SelectedChoice} ({misc.InstalledFiles.Count} files)");
```

--------------------------------

### Get Detailed Dota 2 Version Information

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/auto-patching/SKILL.md

Retrieve detailed version information for the current Dota 2 installation, including the patch version and whether a patch is required.

```csharp
var versionInfo = await versionService.GetVersionInfoAsync(dotaPath);
Console.WriteLine($"Current build: {versionInfo.PatchVersion}");
Console.WriteLine($"Needs patch: {versionInfo.NeedsPatch}");
```

--------------------------------

### Batch Hero Generation Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/services.md

Demonstrates how to use the HeroGenerationService to generate multiple hero sets in batch. Requires Dota 2 path, a list of hero/set selections, and callbacks for logging and progress reporting.

```csharp
var heroGen = serviceProvider.GetRequiredService<HeroGenerationService>();

var selections = new List<(HeroModel hero, string setName)>
{
    (antiMage, "Mage Slayer"),
    (invoker, "Dark Artistry")
};

var result = await heroGen.GenerateBatchAsync(
    dotaPath,
    selections,
    log => Console.WriteLine(log),
    progress => progressBar.Value = progress,
    cancellationToken);
```

--------------------------------

### Program Entry Point using MainForm Factory

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/adr/0002-complete-di-migration-factory-pattern.md

Demonstrates how to resolve the IMainFormFactory from the service provider and use it to create and run the MainForm, passing command-line arguments.

```csharp
// Program.cs — entry point resolving MainForm from factory
var factory = serviceProvider.GetRequiredService<IMainFormFactory>();
bool startMinimized = Environment.GetCommandLineArgs().Any(a => a.Equals("--minimized", StringComparison.OrdinalIgnoreCase));
Application.Run(factory.Create(startMinimized));
```

--------------------------------

### Verify Custom Mod Installation

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/custom-mod-integration/SKILL.md

Check the status of active mods and the overall installation status after a custom mod has been installed. This confirms successful integration.

```csharp
// Check active mods
var activeMods = serviceProvider.GetRequiredService<IActiveModsService>();
var info = await activeMods.GetActiveModsAsync(dotaPath);

Console.WriteLine($"Total active mods: {info.TotalModCount}");
foreach (var hero in info.HeroMods)
    Console.WriteLine($"  Hero: {hero.HeroId} → {hero.SetName}");
foreach (var misc in info.MiscMods)
    Console.WriteLine($"  {misc.Category}: {misc.SelectedChoice}");

// Check status
var status = await statusService.GetDetailedStatusAsync(dotaPath, ct);
Console.WriteLine($"Status: {status.StatusText}");
```

--------------------------------

### Full Auto-Patch Flow Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/auto-patching.md

Implement a complete programmatic auto-patching solution. This snippet demonstrates monitoring for Dota 2 updates and automatically applying patches using IModInstallerService.

```csharp
// Complete programmatic auto-patch implementation
var statusService = serviceProvider.GetRequiredService<IStatusService>();
var installer = serviceProvider.GetRequiredService<IModInstallerService>();

// Monitor for Dota updates
statusService.OnStatusChanged += async newStatus =>
{
    if (newStatus.Status == ModStatus.NeedUpdate)
    {
        Console.WriteLine("Dota 2 updated detected — auto-patching...");

        var result = await installer.UpdatePatcherAsync(
            dotaPath,
            msg => Console.WriteLine($"  {msg}"),
            CancellationToken.None);

        Console.WriteLine(result.Success
            ? "Auto-patch complete!"
            : $"Auto-patch failed: {result.Message}");

        // Force refresh status after patching
        await statusService.ForceRefreshAsync(dotaPath);
    }
};

// Start monitoring
statusService.StartAutoRefresh(dotaPath);
```

--------------------------------

### Initialization Logic for Settings and Launch Options

Source: https://github.com/anneardysa/ardysamodstools/blob/main/Assets/Html/dota2_performance.html

Initializes game settings, default values for console variables, and enables default launch options. It also applies a default preset and renders the UI.

```javascript
// ═══════════════════════════════════════════════════════════
// INIT
// ═══════════════════════════════════════════════════════════
(function init() {
  for (const cat of Object.values(SETTINGS)) {
    for (const [cvar, cfg] of Object.entries(cat.cvars)) {
      currentValues[cvar] = cfg.default;
    }
  }
  LAUNCH_OPTIONS.forEach((opt) => {
    enabledLaunchOptions[opt.flag] = opt.default;
  });
  renderSettings();
  renderLaunchOptions();
  applyPreset("competitive");
})();
```

--------------------------------

### C# File Organization Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/development.md

Demonstrates the recommended file organization structure for C# code, including the order of usings, namespace, class definition, fields, constructor, and methods.

```csharp
// 1. Usings
using System;
using ArdysaModsTools.Core.Interfaces;

// 2. Namespace
namespace ArdysaModsTools.Core.Services;

// 3. Class
public class MyService
{
    // Fields
    private readonly ILogger _logger;

    // Constructor
    public MyService(ILogger logger) { }

    // Public methods
    public Task DoWorkAsync() { }

    // Private methods
    private void Helper() { }
}
```

--------------------------------

### Build ArdysaModsTools Installer

Source: https://github.com/anneardysa/ardysamodstools/blob/main/README.md

Command to build the installer for the ArdysaModsTools application using a Python script. This script is located in the 'scripts/build/' directory.

```bash
python scripts/build/build_installer.py
```

--------------------------------

### Thumbnail URL Pattern Example

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/models.md

Demonstrates how to use the ThumbnailUrlPattern with a placeholder for dynamic URL generation. The placeholder `{choice}` is replaced with a value from the provided choices.

```csharp
var option = new MiscOption
{
    Id = "Weather",
    ThumbnailUrlPattern = "https://cdn.example.com/misc/weather/{choice}.png",
    Choices = new List<string> { "Rain", "Snow", "Harvest" }
};

string url = option.GetThumbnailUrl("Rain");
// Returns: "https://cdn.example.com/misc/weather/rain.png"
```

--------------------------------

### Validate Mod VPK and Check Installation Status

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/mod-file-structure.md

Checks if a mod VPK is valid and if mods are installed correctly in the Dota 2 directory.

```csharp
// Check if mod VPK contains the _ArdysaMods marker
bool isValid = await installer.ValidateVpkAsync(vpkPath, ct);

// Check if mods are installed at a path
bool installed = installer.IsRequiredModFilePresent(dotaPath);
```

--------------------------------

### Show and Update Progress Overlay

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/ui-components.md

Demonstrates how to initialize, show, update progress, and close the ProgressOverlay component. Ensure the ProgressOverlay is properly disposed of after use.

```csharp
using var overlay = new ProgressOverlay(this);
overlay.Show();

await overlay.UpdateProgressAsync(25, "Downloading...");
await overlay.UpdateProgressAsync(50, "Extracting...");
await overlay.UpdateProgressAsync(100, "Complete!");

overlay.Close();
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/CONTRIBUTING.md

Illustrative examples of commit messages following the conventional commit format for features, fixes, and documentation changes.

```git
feat: add hero search functionality
fix: resolve WebView2 crash on startup
docs: update contribution guidelines
```

--------------------------------

### SecurityManager Initialize

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/services.md

Orchestrates security checks at startup.

```APIDOC
## Initialize

### Description
Orchestrates security checks at startup.

### Method
`Initialize(exitOnFailure)`

### Parameters
#### Path Parameters
- **exitOnFailure** (bool) - Required - If true, the application will exit if security checks fail.

#### Returns
- `bool` - True if security checks passed, false otherwise.
```

--------------------------------

### Configure Project to Copy Tools

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/TROUBLESHOOTING.md

Ensure your .csproj file is configured to copy tools to the output directory, resolving 'tools/ Directory Missing' errors.

```xml
<Content Include="tools\**\*">
  <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
```

--------------------------------

### Read and Save Hero Extraction Log

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/mod-file-structure.md

Loads the hero cosmetic set installation log and saves changes. Useful for tracking installed hero assets.

```csharp
// Read hero extraction log
var log = HeroExtractionLog.Load(dotaPath);
if (log != null)
{
    foreach (var entry in log.InstalledSets)
        Console.WriteLine($"{entry.HeroId}: {entry.SetName} ({entry.Files.Count} files)");
}

// Save hero extraction log
var newLog = new HeroExtractionLog();
newLog.InstalledSets.Add(new HeroSetEntry
{
    HeroId = "npc_dota_hero_axe",
    SetName = "Red Mist",
    Files = new List<string> { "models/heroes/axe/axe.vmdl" }
});
newLog.Save(dotaPath);
```

--------------------------------

### Clone, Restore, Build, and Run ArdysaModsTools

Source: https://github.com/anneardysa/ardysamodstools/blob/main/README.md

Standard commands to clone the repository, restore dependencies, build the project, and run the application. Ensure you have the .NET 8.0 SDK and Visual Studio 2022 installed.

```bash
# Clone the repo
git clone https://github.com/Anneardysa/ArdysaModsTools.git
cd ArdysaModsTools

# Restore dependencies
dotnet restore

# Build
dotnet build

# Run
dotnet run

# Run tests
dotnet test Tests/ArdysaModsTools.Tests.csproj
```

--------------------------------

### Register Hero Cosmetic Mod in Extraction Log

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/custom-mod-integration/SKILL.md

Record the installation of hero-specific cosmetic mods in the extraction log. This helps in tracking and managing installed custom files.

```csharp
var log = HeroExtractionLog.Load(dotaPath) ?? new HeroExtractionLog();

log.InstalledSets.Add(new HeroSetEntry
{
    HeroId = "npc_dota_hero_invoker",
    SetName = "Dark Artistry Custom",
    Files = new List<string>
    {
        "models/heroes/invoker/invoker_custom.vmdl_c",
        "materials/models/heroes/invoker/invoker_custom_color.vmat_c",
        "particles/heroes/invoker/custom_orbs.vpcf_c"
    }
});

log.Save(dotaPath);
// Saved to: game/_ArdysaMods/_temp/hero_extraction_log.json
```

--------------------------------

### Startup Security Check

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/adr/0007-security-anti-tamper-architecture.md

Ensures security initialization is performed as the very first action during application startup. If initialization fails, the application exits silently.

```csharp
public static void Main()
{
    if (!SecurityManager.Initialize())
    {
        // Security check failed — exit silently
        return;
    }

    // Continue normal startup...
    Application.Run(factory.Create());
}
```

--------------------------------

### ModInstallerService

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/services.md

Primary service for mod installation operations. It handles downloading, installing, disabling, and updating mods, as well as validating VPK files and checking for new mod packs.

```APIDOC
## ModInstallerService

### Description
Primary service for mod installation operations. It handles downloading, installing, disabling, and updating mods, as well as validating VPK files and checking for new mod packs.

### Key Methods

- **InstallModsAsync**(dotaPath, force, ct): Download and install mod pack. Returns `OperationResult`.
- **DisableModsAsync**(dotaPath, ct): Remove mods, restore original gameinfo. Returns `OperationResult`.
- **ManualInstallModsAsync**(dotaPath, vpkPath, ct): Install user-provided VPK. Returns `OperationResult`.
- **UpdatePatcherAsync**(dotaPath, cb, ct): Patch signatures/gameinfo (full patch). Returns `OperationResult`.
- **ValidateVpkAsync**(vpkPath, ct): Validate VPK contains `_ArdysaMods` marker. Returns `bool`.
- **IsRequiredModFilePresent**(dotaPath): Check if mods installed. Returns `bool`.
- **CheckForNewerModsPackAsync**(dotaPath, ct): Compare local/remote hashes. Returns `bool`.

### Usage Example

```csharp
var installer = serviceProvider.GetRequiredService<ModInstallerService>();

// Install mods
var result = await installer.InstallModsAsync(dotaPath, force: false, ct);
if (!result.Success)
{
    Console.WriteLine($"Install failed: {result.Message}");
    return;
}

// After game update - always does full patch
await installer.UpdatePatcherAsync(dotaPath,
    msg => Console.WriteLine(msg), ct);
```
```

--------------------------------

### Read and Save Misc Extraction Log

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/mod-file-structure.md

Loads and saves the log for miscellaneous mod installations like weather, HUD, and terrain. Allows querying installed files by category.

```csharp
// Read misc extraction log
var log = MiscExtractionLog.Load(dotaPath);
if (log != null)
{
    foreach (var (category, choice) in log.Selections)
        Console.WriteLine($"{category}: {choice}");

    var weatherFiles = log.GetFiles("Weather");
    Console.WriteLine($"Weather files: {weatherFiles.Count}");
}

// Save misc extraction log
var newLog = new MiscExtractionLog
{
    Mode = "CleanGenerate",
    Selections = new Dictionary<string, string>
    {
        ["Weather"] = "Snow"
    }
};
newLog.AddFiles("Weather", new[] { "particles/snow.vpcf" });
newLog.Save(dotaPath);
```

--------------------------------

### Create Custom Hero Skins Workflow

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/user/QUICK_START.md

Steps to select a hero, choose a cosmetic set, and generate custom skins.

```text
Select Hero → Choose hero → Select set → Generate → Wait
```

--------------------------------

### Temporarily Disable Mods

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/user/QUICK_START.md

Instructions to temporarily disable installed mods.

```text
Disable button → Confirm
```

--------------------------------

### Render Launch Options and Table

Source: https://github.com/anneardysa/ardysamodstools/blob/main/Assets/Html/dota2_performance.html

Renders the UI for launch options and their descriptions. This function is called to display the available launch flags and their explanations.

```javascript
function renderLaunchOptions() {
    const container = document.getElementById("launchTags");
    container.innerHTML = "";
    LAUNCH_OPTIONS.forEach((opt) => {
        const enabled = enabledLaunchOptions[opt.flag] ?? opt.default;
        const tag = document.createElement("div");
        tag.className = `launch-tag ${enabled ? "enabled" : ""}`;
        tag.onclick = () => toggleLaunchOption(opt.flag);
        tag.innerHTML = `<span style="font-size:11px;">${enabled ? "[x]" : "[ ]"}</span> <span>${opt.flag}</span>`;
        container.appendChild(tag);
    });
    customLaunchOptions.forEach((opt, i) => {
        const tag = document.createElement("div");
        tag.className = "launch-tag enabled";
        tag.innerHTML = `<span>${opt}</span> <span class="tag-x" onclick="event.stopPropagation(); removeCustomLaunch(${i})">x</span>`;
        container.appendChild(tag);
    });
    updateLaunchString();
    const table = document.getElementById("launchRefTable");
    table.innerHTML = "";
    LAUNCH_OPTIONS.forEach((opt) => {
        const tr = document.createElement("tr");
        tr.className = "border-b border-amt-border/20";
        tr.innerHTML = `<td class="py-2 pr-4 text-amt-accent">${opt.flag}</td><td class="py-2 text-amt-text-dim">${opt.desc}</td>`;
        table.appendChild(tr);
    });
}
```

--------------------------------

### Disable All Mods

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/user/README.md

Procedure to disable all currently installed mods and the required action afterward.

```plaintext
Disable Mods → Restart Dota 2
```

--------------------------------

### Run Test Suite

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/CONTRIBUTING.md

Command to execute the project's test suite using the .NET CLI.

```bash
cd Tests
dotnet test
```

--------------------------------

### Start Drag Operation

Source: https://github.com/anneardysa/ardysamodstools/blob/main/Assets/Html/update_available.html

Initiates a drag operation by sending a 'startDrag' message to the webview.

```javascript
function startDrag() {
  sendMessage({ type: "startDrag" });
}
```

--------------------------------

### Build the Project

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/CONTRIBUTING.md

Command to build the ArdysaModsTools project using the .NET CLI.

```bash
dotnet build
```

--------------------------------

### Check Single Misc Mod

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/skills/query-active-mods/SKILL.md

Retrieves information about a specific installed miscellaneous mod by its category.

```APIDOC
## Get Active Misc Mod

### Description
Retrieves information about a specific installed miscellaneous mod by its category.

### Method
```csharp
var weather = await activeMods.GetActiveMiscModAsync(dotaPath, "Weather");
```

### Parameters
#### Path Parameters
- **category** (string) - Required - The category of the miscellaneous mod (e.g., "Weather", "HUD", "Terrain").

### Response
#### Success Response (ActiveMiscMod?)
- Returns an `ActiveMiscMod` object if the miscellaneous mod is found, otherwise returns null.
  - **Category** (string) - The category of the mod.
  - **SelectedChoice** (string) - The specific choice selected within the category.
  - **InstalledFiles** (IReadOnlyList<string>) - A list of file paths associated with the mod.

### Example Usage
```csharp
var weather = await activeMods.GetActiveMiscModAsync(dotaPath, "Weather");
if (weather != null)
    Console.WriteLine($"Weather: {weather.SelectedChoice}");
```
```

--------------------------------

### Fork and Clone Repository

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/dev/CONTRIBUTING.md

Initial steps to clone the ArdysaModsTools repository and set up the upstream remote for tracking changes.

```bash
# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/ArdysaModsTools.git
cd ArdysaModsTools

# Add upstream remote
git remote add upstream https://github.com/Anneardysa/ArdysaModsTools.git
```

--------------------------------

### ModsPackUpdateService

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/api/services.md

Checks whether a newer ModsPack is available on the remote server compared to the local installation.

```APIDOC
## ModsPackUpdateService

### Description
Checks whether a newer ModsPack is available on the remote server compared to the local installation.

### Key Methods

- **CheckForUpdateAsync**(targetPath, ct): Compares local and remote hashes. Triggers only for existing installs. Returns `Task<bool>`.
```

--------------------------------

### Dota 2 Launch Options

Source: https://github.com/anneardysa/ardysamodstools/blob/main/Assets/Html/dota2_performance.html

These are command-line arguments that can be used to modify Dota 2's startup behavior and performance. They are typically added to the game's launch options in Steam.

```javascript
const LAUNCH_OPTIONS = [
  { flag: "-novid", desc: "Skips the intro video on startup.", default: true },
  { flag: "-console", desc: "Enables the developer console.", default: true },
  { flag: "-fullscreen", desc: "Forces exclusive fullscreen mode.", default: false },
  { flag: "-force_allow_excl_fullscreen", desc: "Allows exclusive fullscreen with compositing.", default: false, },
  { flag: "-coop_fullscreen", desc: "Desktop-friendly fullscreen mode.", default: false },
  { flag: "-force_allow_coop_fullscreen", desc: "Forces cooperative fullscreen support.", default: false, },
  { flag: "-favor_consistent_framerate", desc: "Prioritizes consistent frame times.", default: true, },
  { flag: "-skip_download_player_info", desc: "Skips downloading player info on load.", default: true, },
  { flag: "-high", desc: "Sets process to high priority.", default: false },
  { flag: "-r_max_device_threads 32", desc: "Max rendering threads.", default: false },
  { flag: "-threads 9", desc: "CPU threads for the engine.", default: false },
  { flag: "-mainthreadpriority 2", desc: "Main thread scheduling priority.", default: false, },
  { flag: "-set_power_qos_disable", desc: "Disables Windows power throttling.", default: false, },
  { flag: "-map_enable_background_maps 0", desc: "Disables animated menu backgrounds.", default: false, },
  { flag: "-prewarm_panorama", desc: "Pre-warms UI to reduce first-load stutters.", default: false, },
  { flag: "-noaafonts", desc: "Disables font anti-aliasing.", default: false }
];

let enabledLaunchOptions = {};
let customLaunchOptions = [];
```

--------------------------------

### Clone Repository and Build Project

Source: https://github.com/anneardysa/ardysamodstools/blob/main/docs/developer/development.md

Clone the ArdysaModsTools repository, restore dependencies, build the project in debug mode, and run it.

```bash
# Clone repository
git clone https://github.com/Anneardysa/ArdysaModsTools.git
cd ArdysaModsTools

# Restore dependencies
dotnet restore

# Build debug
dotnet build -c Debug

# Run
dotnet run
```