==============================================================================
  AI Usage Bar — End-User Install & Quick Start
==============================================================================

  This ZIP ships a fully self-contained, portable version of the AI Usage Bar
  + the Setup GUI. You do NOT need to install Python. Python is bundled
  inside `python\` in this archive.

  Tested against:  Windows 10 21H2 and Windows 11 23H2
  Disk needed:     ~300 MB free (the embedded Python is the bulk of the ZIP)
  Internet needed: ONLY if you connect a new provider in Setup for the
                   first time (login flow). After that the bar works offline.

------------------------------------------------------------------------------
  1. Unzip
------------------------------------------------------------------------------
  Right-click AiUsageBar-v1.zip -> "Extract All..." -> pick a folder you
  will leave alone (e.g.  C:\Tools\AiUsageBar).  Do NOT run the bar from
  inside the ZIP — Windows locks files inside open archives.

  After extracting you should see:

      Start AI Usage Bar.cmd
      Setup.cmd
      Start Telegram bot.cmd
      connect-all.cmd
      INSTALL.txt
      PACKAGING.md            (technical — read only if curious)
      app\
          claude_bar.pyw
          providers.py
          kimi_collector.py
          minimax_collector.py
          antigravity_collector.py
          gemini_collector.py
          launch_ai_usage_chrome.cmd
          launch_antigravity_debug.cmd
          product\
              setup_gui.py
              config.py
              requirements.txt
              run_setup.cmd
              usage_bot.py
              run_bot.cmd
              landing\
                  index.html
                  styles.css
      python\                 (bundled Python + PySide6 + websocket-client)

------------------------------------------------------------------------------
  2. Run Setup ONCE
------------------------------------------------------------------------------
  Double-click  Setup.cmd

  The Setup GUI opens. It has five sections, top to bottom:

    1. Welcome      Auto-detects your Chrome path, Claude token, Codex
                    token. Read-only probes — never writes to those files.
                    Click "Re-detect" if you log in to something new.

    2. Providers
        - Claude / Codex    Detect-only. If the pill says "found", you
                            are done for that provider.
        - Kimi              Tick "enable" -> click "Connect" (opens a
                            DEDICATED Chrome on port 9222 with a separate
                            profile so your main Chrome is untouched).
                            Log in to Kimi in that window, come back to
                            Setup, click "Test". When the pill turns green
                            with a real number, you are done.
        - MiniMax           Same dance, also on port 9222. (Kimi, MiniMax
                            and Gemini share the same debug Chrome.)
        - Gemini            Tick "enable" -> click "Connect" (opens
                            gemini.google.com/usage on port 9222). Log in
                            to Google, back in Setup click "Test". Shows a
                            real subscription quota % (current + weekly).
        - Antigravity       Tick "enable" -> click "Connect" (launches
                            Antigravity on port 9223). Open Settings ->
                            Models -> Model Quota in Antigravity, then
                            back in Setup click "Test".

    3. Telegram (optional)
                    Paste your bot token + chat id, click "Test". A
                    "AI Usage Bar connected" message is sent via the
                    official Bot API. Token is never logged.

    4. Startup & bar
                    Tick "Launch at Windows startup" if you want the bar
                    every login (creates a .lnk in your Startup folder).
                    Choose refresh interval in minutes (default 10).
                    Tick which providers appear on the bar.

    5. Finish
                    Click "Save config" — writes %USERPROFILE%\.ai-usage\
                    config.json.
                    Click "Launch bar now" — opens the bar immediately.

------------------------------------------------------------------------------
  3. From now on
------------------------------------------------------------------------------
  - Double-click  Start AI Usage Bar.cmd   any time you want the bar.
  - Double-click  Setup.cmd                any time you want to change
                                           providers, Telegram, or refresh.
  - Double-click  Start Telegram bot.cmd   to run the optional Telegram bot.
                                           Set the bot token + chat id in
                                           Setup (section 3) first. Then message
                                           your bot /usage, or let it push
                                           60% / 85% alerts. Keep the bar
                                           running so the bot has fresh numbers.
  - If you ticked "Launch at Windows startup", the bar starts automatically
    every time you log in. No further action needed.

------------------------------------------------------------------------------
  Which windows to KEEP OPEN vs CLOSE   (important!)
------------------------------------------------------------------------------

  KEEP RUNNING  (if you close it, that feature stops):
    * The bar        "Start AI Usage Bar.cmd" — the taskbar display; it also
                     refreshes every provider's numbers every few minutes.
    * Debug Chrome   opened by "Connect" / connect-all.cmd — stay logged in.
                     Kimi / MiniMax / Gemini numbers are read from it.
                     MINIMIZE it, don't close it.
    * Antigravity    (only if you track it) open at Settings > Models >
                     Model Quota.
    * Telegram bot   "Start Telegram bot.cmd" — needed for /usage + alerts.
                     It runs hidden (no window); stop it via Task Manager
                     (end pythonw.exe) when you want it off.

  SAFE TO CLOSE:
    * Setup.cmd      one-time setup. Close it AFTER you click "Save config".
                     Re-open only to change providers / token / refresh.
    * connect-all.cmd  it just launches the browser(s) then closes itself —
                     that's normal. The browser windows it opened stay.

------------------------------------------------------------------------------
  4. Troubleshooting
------------------------------------------------------------------------------

Q: Double-clicking Setup.cmd flashes a black window and closes.
A: The window was too quick to read. Open it from a cmd prompt instead:
       cd "C:\Tools\AiUsageBar"
       Setup.cmd
   Read the error message. Most common cause: antivirus deleted python\
   right after unzip. Add an exclusion for the AiUsageBar folder.

Q: "Embedded python not found" error.
A: The ZIP was not fully extracted, or your antivirus quarantined python\.
   Re-extract the ZIP and check your AV quarantine list.

Q: The bar opens but only Claude shows — Kimi/MiniMax/Antigravity are N/A.
A: You have to "Connect" then "Test" each in Setup.cmd first. The bar
   only displays a provider once it has a green "ok" cache file at
   %USERPROFILE%\.cache\ai_usage\<provider>.json.

Q: Antigravity "Connect" says the .exe was not found.
A: Right-click your Antigravity desktop shortcut -> Properties -> Target.
   Copy the full path and send it back to the developer; the launcher
   will be updated to point at it.

Q: A provider's number is "Stale" / amber.
A: The cache is older than 2x your refresh interval. Either the collector
   crashed (open a terminal, run it manually to see the error) or the
   debug browser was closed. Re-open it via Setup -> Connect.

Q: I want to uninstall.
A: Delete the AiUsageBar folder. Optional cleanup:
       del /S /Q  %USERPROFILE%\.ai-usage\
       del /S /Q  %USERPROFILE%\.cache\ai_usage\
   Those folders hold your config + per-provider cache; nothing else
   outside the AiUsageBar folder is touched.

Q: Is anything written outside the AiUsageBar folder?
A: Yes, exactly two things, both read-only-safe:
       %USERPROFILE%\.ai-usage\config.json       (your choices)
       %USERPROFILE%\.cache\ai_usage\*.json      (provider percentages)
   NO credential files (Claude .credentials.json, Codex auth.json, etc.)
   are ever written by this program — read-only by design.

------------------------------------------------------------------------------
  5. Privacy
------------------------------------------------------------------------------
  - The Setup GUI probes Claude/Codex tokens read-only.
  - Collectors read the live usage pages of logged-in providers via the
    Chrome DevTools Protocol — they NEVER type, NEVER scrape cookies, and
    NEVER exfiltrate anything off your machine.
  - Telegram messages are sent ONLY when you click "Test" in section 3,
    or from the optional Telegram bot ("Start Telegram bot.cmd", shipped here).
  - No telemetry, no analytics, no auto-update pings.

------------------------------------------------------------------------------
  6. License / credits
------------------------------------------------------------------------------
  Powered by BaeProduction.  Open source, donate if it saved you time:
  https://baepat.com/ai-usage  (placeholder — real URL in Setup GUI)

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