============================================
  MuraveyChina — Troubleshooting Guide
  (All Known Problems & Solutions)
============================================


  1. WINDOWS SECURITY BLOCKS THE PROGRAM
  ───────────────────────────────────────

  PROBLEM: SmartScreen says "Windows protected your PC"
  SOLUTION:
    1. Click "More info"
    2. Click "Run anyway"

  PROBLEM: Smart App Control blocks the program (Windows 11)
  SOLUTION:
    1. Open Windows Settings (Win + I)
    2. Privacy & Security → Windows Security → Open
    3. App & browser control → Smart App Control settings
    4. Select "Off" → Confirm "Yes"

  PROBLEM: Windows Defender quarantines files
  SOLUTION:
    1. Open Windows Security
    2. Virus & threat protection → Manage settings
    3. Scroll to Exclusions → Add or remove exclusions
    4. Add an exclusion → Folder
    5. Select your MuraveyChina folder (e.g. the installation folder)
    6. ALSO add Python folder:
       C:\Users\YourName\AppData\Local\Programs\Python\

  PROBLEM: INSTALL.bat won't run
  SOLUTION:
    1. Right-click INSTALL.bat → Properties
    2. Check "Unblock" at the bottom
    3. Click OK
    4. Try again


  2. PYTHON PROBLEMS
  ──────────────────

  PROBLEM: "python is not recognized"
  SOLUTION:
    Reinstall Python from python.org
    IMPORTANT: Check "Add Python to PATH" during install!

  PROBLEM: Wrong Python version
  SOLUTION:
    Need Python 3.10 or higher. Check:
    python --version
    If lower than 3.10 — reinstall from python.org

  PROBLEM: Multiple Python versions installed
  SOLUTION:
    Use the correct one:
    py -3.11 launch.py
    Or uninstall old versions from Settings → Apps


  3. MODEL DOWNLOAD PROBLEMS
  ──────────────────────────

  PROBLEM: Download stuck or very slow
  SOLUTION:
    - Check internet connection
    - Models are ~6.6 GB total, needs stable connection
    - Try running INSTALL.bat again — it will resume

  PROBLEM: "SSL error" during download
  SOLUTION:
    - Your network may block huggingface.co
    - Use VPN or different network
    - Or download models manually in browser:
      https://huggingface.co/ggml-org/Qwen2.5-VL-3B-Instruct-GGUF
      https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF
    - Put files in: %USERPROFILE%\.muravey-china\models\

  PROBLEM: "Model not found" when running
  SOLUTION:
    Check files exist:
    dir "%USERPROFILE%\.muravey-china\models\qwen25vl\"
    Should show 2 files (~1.8 GB and ~1.2 GB)
    dir "%USERPROFILE%\.muravey-china\models\"
    Should show qwen2.5-7b-instruct-q3_k_m.gguf (~3.6 GB)

  PROBLEM: Model file is too small (incomplete download)
  SOLUTION:
    Delete and re-download:
    del "%USERPROFILE%\.muravey-china\models\qwen25vl\*.gguf"
    del "%USERPROFILE%\.muravey-china\models\*.gguf"
    Run INSTALL.bat again


  4. llama-cpp-python PROBLEMS
  ────────────────────────────

  PROBLEM: "Failed building wheel for llama-cpp-python"
  SOLUTION:
    Install Visual Studio Build Tools first:
    https://visualstudio.microsoft.com/visual-cpp-build-tools/
    Select "Desktop development with C++"
    Then run INSTALL.bat again

  PROBLEM: "RuntimeError: Failed to load ggml"
  SOLUTION:
    Reinstall llama-cpp-python:
    pip uninstall llama-cpp-python -y
    set CMAKE_ARGS=-DGGML_CUDA=OFF
    pip install llama-cpp-python==0.3.19 --no-cache-dir

  PROBLEM: GPU version doesn't work
  SOLUTION:
    The program works on CPU too. Just slower.
    For GPU you need:
    1. NVIDIA GPU
    2. CUDA Toolkit: developer.nvidia.com/cuda-downloads
    3. Add to PATH: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.0\bin\x64


  5. ACTIVATION PROBLEMS
  ──────────────────────

  PROBLEM: Activation window doesn't appear
  SOLUTION:
    Machine ID is ALSO shown in the console (black window).
    Look there. Or run manually:
    1. Open cmd
    2. cd /d the installation folder
    3. python launch.py
    4. Machine ID will appear in console

  PROBLEM: Token not accepted
  SOLUTION:
    - Copy the ENTIRE token (starts with MC-v1-)
    - Token is valid for 24 hours only
    - Token is bound to ONE computer only
    - Make sure you copy without extra spaces

  PROBLEM: "Error: Token expired"
  SOLUTION:
    Buy a new token at license.muravey.app/buy

  PROBLEM: "Error: Machine ID mismatch"
  SOLUTION:
    Token was generated for a different computer.
    You need a token for YOUR machine ID.


  6. HOTKEY PROBLEMS
  ──────────────────

  PROBLEM: Ctrl+` doesn't work
  SOLUTION:
    1. Make sure program is running (check tray icon)
    2. Run as Administrator:
       Right-click MuraveyChina shortcut → Run as administrator
    3. If inside CSCA — wait 5 seconds for auto-detection

  PROBLEM: Hotkeys work sometimes, not always
  SOLUTION:
    - Don't press the shortcut multiple times rapidly
    - Wait for "..." to appear before pressing again
    - If program is already processing — it will ignore

  PROBLEM: Old hotkey (Ctrl+Shift+F7) doesn't work
  SOLUTION:
    New hotkey is Ctrl+`
    Delete old config:
    del "%APPDATA%\MuraveyChina\config.yaml"
    Restart program


  7. PERFORMANCE PROBLEMS
  ───────────────────────

  PROBLEM: Takes more than 2 minutes
  SOLUTION:
    First question is always slow (model loading).
    After that it should be 15-50 seconds.
    If always slow — you don't have GPU (CPU mode).

  PROBLEM: "..." shows forever
  SOLUTION:
    - First time: wait up to 2 minutes
    - If stuck: press Ctrl+C in console, restart
    - Check that models downloaded completely

  PROBLEM: ".." appears (error)
  SOLUTION:
    - Make the question text bigger on screen
    - Make sure full question is visible
    - Try pressing Ctrl+` again


  8. CSCA/EXAM SOFTWARE PROBLEMS
  ──────────────────────────────

  PROBLEM: Hotkeys don't work inside CSCA
  SOLUTION:
    Run as Administrator. Right-click cmd → Run as administrator
    Then: cd /d the installation folder && python launch.py

  PROBLEM: Network blocked inside CSCA
  SOLUTION:
    This is normal. The program works OFFLINE.
    No internet needed during exam.

  PROBLEM: Program closes when CSCA starts
  SOLUTION:
    Start MuraveyChina BEFORE opening CSCA.


  9. STALE FILES / CACHE PROBLEMS
  ───────────────────────────────

  PROBLEM: Program behaves differently after update
  SOLUTION:
    Clear cache:
    cd /d the installation folder
    for /r %d in (__pycache__) do @if exist "%d" rd /s /q "%d"
    del "%APPDATA%\MuraveyChina\config.yaml"
    Restart program


  10. ENCODING PROBLEMS
  ─────────────────────

  PROBLEM: Chinese text shows as "???" or garbled
  SOLUTION:
    Run cmd with UTF-8:
    chcp 65001
    Then: python launch.py


============================================
  COMPLETE RESET (if nothing works)
============================================

  1. Uninstall Python completely
  2. Delete folders:
     - the installation folder (or wherever you extracted)
     - %APPDATA%\MuraveyChina\
     - %USERPROFILE%\.muravey-china\
  3. Reinstall Python 3.11 (check "Add to PATH"!)
  4. Extract fresh MuraveyChina.zip
  5. Follow ANTIVIRUS_SETUP guide first
  6. Run INSTALL.bat
  7. Activate with token

============================================
