================================================================================
  FOREVERAI CHATBOT & COMPANION (v1.2.0)
  COMPLETE LOCAL INSTALLATION & CURSEFORGE.COM UPLOAD GUIDE
================================================================================

TABLE OF CONTENTS
-----------------
  1. ARCHITECTURE OVERVIEW (WHAT GETS INSTALLED WHERE)
  2. QUICK ONE-CLICK LOCAL INSTALLATION (WINDOWS, MACOS, LINUX)
  3. DETAILED STEP-BY-STEP LOCAL INSTALLATION
     3A. Installing the Desktop Companion Suite (ForeverCompanion)
     3B. Installing the In-Game World of Warcraft Addon (ForeverAIChatbot)
     3C. Connecting SavedVariables (wtf_path) for Live In-Game Sync
  4. CONFIGURING GOOGLE GEMINI AI (ULTRA-LOW-COST / FREE TIER)
  5. LAUNCHING & USING FOREVERAI (PRESS-TO-TALK, SCREEN SHARE, COMMANDS)
  6. CONTENT & FILES TO UPLOAD TO CURSEFORGE.COM
     6A. What Files Go to CurseForge.com vs. GitHub Releases
     6B. Step-by-Step Manual Upload to CurseForge.com
     6C. Automated Upload via API Token (release.bat / upload_curseforge.py)
  7. TROUBLESHOOTING & VERIFICATION CHECKLIST


================================================================================
1. ARCHITECTURE OVERVIEW (WHAT GETS INSTALLED WHERE)
================================================================================

ForeverAI consists of two components that work together:

  [A] ForeverAIChatbot (In-Game World of Warcraft Addon - Lua/XML)
      - Installed inside your World of Warcraft "Interface/AddOns/" folder.
      - Provides the resizable circular "F-AI" HUD orb, the "World of Warcraft:
        Forever" AI Response Window (for both text & visual answers), automatic
        Resource Node Location Tracking with small icons on the World Map &
        Minimap, Press-to-Talk [HOLD V TO SPEAK] button & green mic indicator,
        animated AI sound-line waves, and automatic combat/loot/death logging.
      - THIS IS THE ONLY PACKAGE UPLOADED TO CURSEFORGE.COM:
        -> dist/ForeverAIChatbot-v1.2.0-Addon.zip

  [B] ForeverCompanion (Local Desktop Companion App - Python/FastAPI/Web UI)
      - Installed on your local PC (in this project folder or extracted from
        dist/ForeverCompanion-v1.2.0-Desktop.zip).
      - Runs the local AI tactical brain (powered by Gemini 2.5 Flash-Lite
        with full offline fallback), Live Voice Engine (Speech-to-Text +
        4-persona Text-to-Speech), Screen Sharing OCR Vision Monitor,
        SQLite Gameplay & Resource Node Database, and Web Dashboard at:
        -> http://localhost:8080


================================================================================
2. QUICK ONE-CLICK LOCAL INSTALLATION (WINDOWS, MACOS, LINUX)
================================================================================

WINDOWS (One-Click Installer):
------------------------------
  1. Ensure Python 3.9 or newer is installed (https://www.python.org/downloads/).
     * Make sure "[x] Add python.exe to PATH" was checked during Python setup.
  2. Double-click "install.bat" in the ForeverAI root folder.
  3. The installer will automatically:
     - Create an isolated Python virtual environment (.venv)
     - Install all required Python packages (companion/requirements.txt)
     - Generate the application icon (icon.ico) and SVG visual assets
     - Create "ForeverAI Companion" shortcuts on your Windows Desktop and
       Start Menu
     - Scan your computer for World of Warcraft installations (_retail_,
       _classic_era_, _classic_, _ptr_, or standalone Vanilla 1.12) and
       automatically copy the "ForeverAIChatbot" addon into every detected
       "Interface\AddOns\ForeverAIChatbot" folder!
     - Configure your "wtf_path" and "gemini-2.5-flash-lite" model in config.json.

  * NOTE: If your World of Warcraft client is installed in a custom folder on
    another drive that was not auto-detected, run:
      install.bat --wow-path "D:\Your\Custom\Path\World of Warcraft"

LINUX / MACOS (One-Command Installer):
--------------------------------------
  1. Open a terminal in the ForeverAI folder and run:
       chmod +x install.sh run.sh
       ./install.sh
  2. Or specify your World of Warcraft folder explicitly:
       ./install.sh --wow-path "/Applications/World of Warcraft"


================================================================================
3. DETAILED STEP-BY-STEP LOCAL INSTALLATION
================================================================================

--------------------------------------------------------------------------------
3A. Installing the Desktop Companion Suite (ForeverCompanion)
--------------------------------------------------------------------------------
If you prefer to set up each step manually instead of using install.bat:

  Step 1: Create the Virtual Environment
    Open PowerShell or Command Prompt in the ForeverAI folder and run:
      python -m venv .venv

  Step 2: Install Dependencies Inside .venv
    Windows:
      .\.venv\Scripts\python.exe -m pip install -r companion\requirements.txt
    Linux / macOS:
      ./.venv/bin/python -m pip install -r companion/requirements.txt

  Step 3: Run the Local Device Setup Script
    Windows:
      .\.venv\Scripts\python.exe scripts\install_local.py
    Linux / macOS:
      ./.venv/bin/python scripts/install_local.py --skip-shortcuts

--------------------------------------------------------------------------------
3B. Installing the In-Game World of Warcraft Addon (ForeverAIChatbot)
--------------------------------------------------------------------------------
If `scripts/install_local.py` already found your World of Warcraft installation,
the addon is already installed!

To install or verify the addon manually:
  1. Locate the "ForeverAIChatbot" folder in this project (or extract
     "dist/ForeverAIChatbot-v1.2.0-Addon.zip").
  2. Copy the "ForeverAIChatbot" folder directly into your World of Warcraft
     client's "Interface/AddOns/" directory:

     - Retail (The War Within 11.0+):
       C:\Program Files (x86)\World of Warcraft\_retail_\Interface\AddOns\ForeverAIChatbot

     - Classic Era / Forever (1.15.x):
       C:\Program Files (x86)\World of Warcraft\_classic_era_\Interface\AddOns\ForeverAIChatbot

     - Cataclysm / WotLK Classic (4.4 / 3.4):
       C:\Program Files (x86)\World of Warcraft\_classic_\Interface\AddOns\ForeverAIChatbot

     - Standalone / Vanilla 1.12 Client:
       <Your WoW Folder>\Interface\AddOns\ForeverAIChatbot

  3. Verify the folder structure is NOT double-nested. The file
     "ForeverAIChatbot.toc" must exist directly at:
       .../Interface/AddOns/ForeverAIChatbot/ForeverAIChatbot.toc

  4. Launch World of Warcraft:
     - On the Character Selection screen, click the "AddOns" button in the
       bottom-left corner.
     - Ensure "ForeverAI Chatbot & Companion" is checked (Enabled).
     - Enter the world. You will see in chat:
       [ForeverAI] Loaded successfully. Type /fai to toggle advisor window or /fai opt for settings.

--------------------------------------------------------------------------------
3C. Connecting SavedVariables (wtf_path) for Live In-Game Sync
--------------------------------------------------------------------------------
To allow the Desktop Companion to automatically read your in-game combat logs,
loot drops, deaths, and voice triggers when you `/reload` or zone:

  1. Open `config.json` in the ForeverAI root folder (or click the Gear icon
     in the top-right corner of the Web Dashboard at http://localhost:8080).
  2. Set `"wtf_path"` to your WoW client's WTF folder, for example:
       "wtf_path": "C:\\Program Files (x86)\\World of Warcraft\\_classic_era_\\WTF"
     (Note: `install.bat` / `scripts/install_local.py` sets this automatically
     when it detects your WoW installation.)


================================================================================
4. CONFIGURING GOOGLE GEMINI AI (ULTRA-LOW-COST / FREE TIER)
================================================================================

ForeverAI is pre-configured to use Google's cheapest, highest-efficiency
multimodal model:
  - Primary Default Model : gemini-2.5-flash-lite ($0.10/1M input, $0.40/1M output)
  - Automatic Fallbacks   : gemini-2.0-flash-lite -> gemini-2.5-flash ->
                            gemini-2.0-flash -> gemini-1.5-flash-8b
  - Built-in Offline Mode : Works immediately with zero API key using the
                            built-in World of Warcraft tactical database!

To enable live Google Gemini Cloud AI responses:
  Option 1 (Web Dashboard UI):
    1. Launch ForeverAI and open http://localhost:8080.
    2. Click the Gear Icon (Settings) in the top-right header.
    3. Paste your free Google AI Studio API Key (https://aistudio.google.com/app/apikey)
       into the "Gemini API Key" field and select "Gemini 2.5 Flash-Lite".
    4. Click Save.

  Option 2 (.env File):
    Create a file named `.env` in the ForeverAI root directory containing:
      GEMINI_API_KEY=your_api_key_here


================================================================================
5. LAUNCHING & USING FOREVERAI (PRESS-TO-TALK, SCREEN SHARE, COMMANDS)
================================================================================

LAUNCHING THE APP:
  - Windows Desktop : Double-click the "ForeverAI Companion" icon on your Desktop
                      (or double-click `run.bat`).
  - Linux / macOS   : Run `./run.sh` (or `python3 run.py`).
  - Web Dashboard   : Automatically opens in Chrome/Browser at http://localhost:8080.

USING LIVE PRESS-TO-TALK (PTT) VOICE CHAT:
  - On the Web Dashboard (http://localhost:8080):
    * Hold the [V] key (when not typing in a text input) OR click-and-hold the
      "Hold [V] or Click to Talk" button on the Live Voice Engine card.
    * Speak your question (e.g., "Where does Lion Meat drop at the lowest level?"
      or "What should I do on Onyxia Phase 2?").
    * Release [V]. Your speech is transcribed, sent to the AI Advisor with your
      live screen context, and spoken back to you in your chosen persona voice!
    * To change the PTT key: Click the `[V]` key badge on the Voice card (or in
      Settings) and press any key or mouse button.

  - Inside World of Warcraft:
    * Hold [V] (while not typing in chat) or click-and-hold the `[HOLD V TO SPEAK]`
      button inside the `/fai` Advisor window.
    * Right-click the `[HOLD V TO SPEAK]` button (or type `/fai ptt <KEY>`, or open
      `Esc -> Options -> AddOns -> ForeverAI Chatbot`) to rebind your in-game PTT key.
    * You can also bind it in WoW's native `Esc -> Options -> Keybindings -> ForeverAI Companion`.

IN-GAME SLASH COMMANDS:
  /fai              - Toggle the main ForeverAI Advisor window
  /fai ask <query>  - Ask the AI advisor a question & open the "World of Warcraft: Forever" window
  /fai node [cmd]   - Track resource nodes (`add <Name>`, `toggle`, `clear`) & Map/Minimap pins
  /fai ptt [key]    - Rebind your Press-to-Talk key (e.g., `/fai ptt V` or `/fai ptt MOUSE4`)
  /fai voice        - Toggle Live Voice Chat on/off
  /fai screen       - Toggle Screen Monitor status
  /fai web          - Open the Web Companion Dashboard (http://localhost:8080) in Chrome
  /fai opt          - Open the native Blizzard Options panel for ForeverAI
  /fai db           - Show Gameplay & Resource Node statistics summary
  /fai clear        - Clear the in-game advisor chat log


================================================================================
6. CONTENT & FILES TO UPLOAD TO CURSEFORGE.COM
================================================================================

--------------------------------------------------------------------------------
6A. What Files Go to CurseForge.com vs. GitHub Releases
--------------------------------------------------------------------------------
IMPORTANT CURSEFORGE POLICY:
CurseForge strictly prohibits executables (.exe, .bat, .sh) and Python scripts
inside World of Warcraft addon zip uploads. All release files have already been
built and verified in the `dist/` folder:

  1. UPLOAD THIS FILE TO CURSEFORGE.COM:
     -> dist/ForeverAIChatbot-v1.2.0-Addon.zip
     Contains ONLY the pure Lua/XML/TOC World of Warcraft addon inside the
     `ForeverAIChatbot/` root folder:
       - ForeverAIChatbot/ForeverAIChatbot.toc (with Version: v1.2.0)
       - ForeverAIChatbot/Bindings.xml
       - ForeverAIChatbot/Audio.lua
       - ForeverAIChatbot/Core.lua
       - ForeverAIChatbot/DatabaseTracker.lua
       - ForeverAIChatbot/MinimapButton.lua
       - ForeverAIChatbot/UI.lua
       - ForeverAIChatbot/Options.lua
       - ForeverAIChatbot/LICENSE.txt

  2. USE THESE PREPARED CURSEFORGE SUBMISSION FILES (IN `dist/`):
     -> dist/CURSEFORGE_DESCRIPTION.md
        (Ready-to-paste Markdown description for your CurseForge project page)
     -> dist/CURSEFORGE_CHANGELOG_v1.2.0.md
        (Ready-to-paste Markdown changelog for the v1.2.0 file upload)
     -> dist/CURSEFORGE_UPLOAD_INFO.txt
        (All CurseForge form fields: Title, Slug, Summary, Categories, Game
        Versions, License, and step-by-step upload checklist)
     -> dist/ForeverAI-CurseForge-Avatar-512x512.png
        (512x512 PNG project icon/avatar for your CurseForge project page)

  3. UPLOAD THIS FILE TO GITHUB RELEASES (OR LOCAL DISTRIBUTION):
     -> dist/ForeverCompanion-v1.2.0-Desktop.zip
        (Complete standalone Desktop Companion + Local Installer + Addon bundle)

  * To regenerate all files in `dist/` at any time, run:
      .\.venv\Scripts\python.exe scripts\package_release.py

--------------------------------------------------------------------------------
6B. Step-by-Step Manual Upload to CurseForge.com
--------------------------------------------------------------------------------
  Step 1: Go to https://authors.curseforge.com and sign in.
  Step 2: Create or open your World of Warcraft Addon project:
    - Project Name        : ForeverAI Chatbot & Companion
    - Project Slug        : foreverai-chatbot
    - Summary             : Real-time AI tactical advisor featuring the resizable F-AI Circle HUD, World of Warcraft: Forever response window, Resource Node Map/Minimap pins, and live voice chat.
    - Primary Category    : Combat
    - Secondary Categories: Quests, Audio & Video, Miscellaneous, Map & Minimap
    - License             : MIT License
    - Avatar              : Upload `dist/ForeverAI-CurseForge-Avatar-512x512.png`
    - Description         : Copy and paste the contents of `dist/CURSEFORGE_DESCRIPTION.md`
  Step 3: Upload the Addon File:
    - Click "Files" -> "Upload File"
    - Select File         : `dist/ForeverAIChatbot-v1.2.0-Addon.zip`
    - Display Name        : `ForeverAI Chatbot & Companion v1.2.0`
    - Release Type        : `Release`
    - Changelog Type      : `Markdown`
    - Changelog           : Copy and paste the contents of `dist/CURSEFORGE_CHANGELOG_v1.2.0.md`
    - Supported Versions  : Select Retail (`11.0.2`), Classic Era (`1.15.3`),
                            Cataclysm Classic (`4.4.0`), WotLK (`3.4.3`).
    - Click "Submit File".

--------------------------------------------------------------------------------
6C. Automated Upload via API Token (release.bat / upload_curseforge.py)
--------------------------------------------------------------------------------
You can also upload directly to CurseForge from the command line or GitHub Actions:

  1. Generate an API Token at: https://authors.curseforge.com/account/api-tokens
  2. Run the direct uploader:
       set CF_API_KEY=your_curseforge_token_here
       .\.venv\Scripts\python.exe scripts\upload_curseforge.py --version 1.2.0
  3. Or run `release.bat` to bump versions, run tests, package both zips, tag git,
     and publish to CurseForge automatically.


================================================================================
7. TROUBLESHOOTING & VERIFICATION CHECKLIST
================================================================================

  [1] Run the Automated Verification Suite (60+ Unit Tests):
        .\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_*.py" -v

  [2] Addon Does Not Appear in WoW Character Select -> AddOns:
      - Run `install.bat --wow-path "C:\Path\To\World of Warcraft"`
      - Ensure `ForeverAIChatbot.toc` is located directly inside:
        `<WoW>\_retail_\Interface\AddOns\ForeverAIChatbot\ForeverAIChatbot.toc`
      - Enable "[x] Load out of date AddOns" in the AddOns menu if running on a
        newly patched WoW build.

  [3] Press-to-Talk Microphone Permission in Browser:
      - When holding `[V]` on `http://localhost:8080` for the first time, click
        "Allow" when Chrome/Edge prompts for microphone access.
      - If speech recognition is unavailable in your browser, ForeverAI
        automatically falls back to raw PCM audio capture and server-side
        transcription via `/api/voice/transcribe`.
================================================================================
