Initial release: Joker Combo Advisor v1.0.0

Steamodded mod that teaches Balatro joker synergies: hover tooltips
explain why jokers combo (famous-pair blurbs + tag-based reasons),
combo discovery tracking with catalog grey-out and run recap, an
in-game synergy catalog with real card sprites, learning mode, and
a HUD shortcut.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,95 @@
+# Joker Combo Advisor
+
+A [Steamodded](https://github.com/Steamodded/smods) mod for Balatro that
+recommends joker combos while you play:
+
+- **Hover any joker in the shop or a Buffoon Pack** and a *Combo Advisor*
+  tooltip appears next to its description, naming which of your current
+  jokers it synergizes with **and why** ("Mime: retriggers cards in hand"),
+  so you learn the mechanics rather than just the verdict. Famous pairs get
+  hand-written explanations; everything else is phrased from the synergy
+  tags. Jokers with no current synergy teach instead what to pair them with
+  ("Looking for: Tarot cards" / "Offers: face cards"). Strong picks also get
+  a "Strong pick for this build!" callout and **pulse periodically** in the
+  shop so you can spot them without hovering.
+- **Combo discovery**: the first time you field a famous pair together, a
+  "New combo!" toast fires and the pair is permanently inked into the
+  catalog — until then its cards sit face-down with a "???" caption, so
+  filling in the Combos tab becomes its own collection hunt.
+- **Hover a joker you own** to see its active combos with the rest of your
+  lineup.
+- **Browse the synergy catalog** any time: a purple **Combos** button in the
+  run HUD (under Run Info / Options) opens it in an overlay, and the same
+  tabs live under Mods > Combo Advisor. The *Combos* tab shows the famous
+  pairs as card duos with their explanation once fielded; *Engine* /
+  *Economy* / *Hands* tabs page through each synergy theme with a one-line
+  explanation of the mechanic and its **Sources** and **Payoffs** as real
+  cards — hover any card for its normal description tooltip. All of it is generated
+  from the same database the advisor scores with. Jokers you haven't
+  discovered yet show face-down (no spoilers) unless the profile has used
+  the game's own **Unlock All** setting, in which case everything is shown.
+- **Post-run combo recap**: the win and game-over screens list the famous
+  pairs you fielded during that run.
+
+## How recommendations work
+
+`synergies.lua` tags all 150 vanilla jokers with what they *give* a build
+(e.g. `retrig_scoring`, `gold_gen`, `xmult`) and what they *want*
+(e.g. `faces`, `probability`, `money`). Two jokers score:
+
+| Signal | Points |
+| --- | --- |
+| Famous explicit pair (Baron + Mime, Midas Mask + Golden Ticket, …) | +4 |
+| Each *gives* tag the other *wants* (both directions) | +2 |
+| Generic engine complement (+Mult/+Chips source with an ×Mult joker) | +1 |
+
+A shop joker is *recommended* (pulses) when its total score against your
+owned jokers reaches the configured threshold (default 4). Partners with a
+pairwise score of 2+ are listed in the tooltip, strongest first.
+
+## Settings
+
+In-game: **Mods > Combo Advisor > Config**. Changes persist across sessions.
+
+- **Pulse recommended jokers in shop** — turn the visual pulse on/off.
+- **Show combo tooltip on owned jokers** — the "Active combos" section on
+  jokers you already hold.
+- **Learning mode** — hides the verdicts (pulse and "Strong pick!") while
+  keeping all the explanations, for players who want to learn the synergies
+  rather than be told what to buy.
+- **Recommendation threshold** — 2 (chatty) to 8 (only slam-dunk combos).
+
+Defaults live in `config.lua`.
+
+## Installation
+
+1. Install [Lovely](https://github.com/ethangreen-dev/lovely-injector) and
+   [Steamodded](https://github.com/Steamodded/smods) (follow their READMEs).
+2. Copy this whole folder into your Balatro `Mods` directory:
+   - **Windows:** `%AppData%/Balatro/Mods/`
+   - **Linux (Steam/Proton):**
+     `~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/`
+     (or the same path under `~/.steam/steam/`, or
+     `~/.var/app/com.valvesoftware.Steam/.local/share/Steam/...` for Flatpak Steam)
+   - **macOS:** `~/Library/Application Support/Balatro/Mods/`
+3. Launch Balatro. The mod should appear in the in-game **Mods** menu.
+   If something goes wrong, check the Lovely log
+   (`Mods/lovely/log/` next to the game, or the console window on launch).
+
+## Extending it
+
+- **Add or fix a synergy:** edit `synergies.lua`. Give a joker a tag with
+  `j('j_key', {gives...}, {wants...})`, or add a famous pair to the `PAIRS`
+  table at the bottom. Modded jokers can be added the same way using their
+  full key (e.g. `j_mymod_cooljoker`) — unknown jokers simply score 0.
+- **Tune sensitivity:** use the in-game Config tab, or change the defaults
+  in `config.lua`.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `JokerComboAdvisor.json` | Steamodded mod metadata |
+| `main.lua` | Scoring engine, hover tooltip, shop pulse, config tab |
+| `synergies.lua` | Tag database for all 150 vanilla jokers + famous pairs |
+| `config.lua` | Default settings (persisted by Steamodded once changed in-game) |