Document the new features in README and CLAUDE.md

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

CLAUDE.md

@@ -74,12 +74,24 @@ Three-layer split; `JCA` is the single global namespace:
   - UI hooks: wraps `Card:generate_UIBox_ability_table` to append a tooltip entry
     to `aut.info` (format: array of rows-of-UIT-nodes plus a `.name` string —
     must match what vanilla `info_tip_from_rows` expects), and wraps
-    `Card:update` for the ~2.5s pulse on recommended shop cards. Both hook bodies
+    `Card:update` for the ~2.5s pulse on recommended shop cards and the
-    are pcall-wrapped so a scoring bug can never crash a run — keep it that way.
+    partner highlight (hovering a joker juices its owned partners ~0.9s;
+    partner set cached on the card as `jca_hl`, dropped when hover ends).
+    All hook bodies are pcall-wrapped so a scoring bug can never crash a
+    run — keep it that way.
+  - Sell advisor: `JCA.weakest_link()` (full board + ≥3 jokers + a strict
+    minimum required, else nil) flags the lowest-total owned joker with a
+    red verdict row; suppressed by learning mode, toggled by
+    `config.sell_advisor`.
+  - Public API for other mods: `JCA.register(key, gives, wants, opts)`,
+    `JCA.register_pair(a, b, blurb)` (sets `JCA._pairs_dirty` so the
+    Combos tab re-sorts), `JCA.register_clash(a, b, warning)`. Unknown
+    tags are dropped with a log line, never an error.
   - Config tab: registered on `SMODS.current_mod.config_tab`, guarded by
     `if SMODS.current_mod` so standalone tests don't need full stubs.
   - Synergy catalog: `SMODS.current_mod.extra_tabs` adds Combos/Engine/
-    Economy/Hands tabs that render real `Card` objects in `CardArea`s
+    Economy/Hands tabs (plus a text-only Progress tab with discovery
+    completion bars) that render real `Card` objects in `CardArea`s
     (collection-style, so hover shows each joker's own tooltip). One theme
     per page; pagers swap the `tab_contents` UIBox from an option-cycle
     callback — the same pattern as SMODS's achievements tab. Because pages

README.md

@@ -20,8 +20,18 @@ recommends joker combos while you play:
   one joker that provides it plus another that wants it — fires a
   "Theme explored!" toast, badges that theme's catalog page, and counts
   toward a per-tab progress line ("3 of 10 themes explored").
+- **Anti-synergy warnings**: known traps get a red "Clashes" line when a
+  hovered joker fights one you own (Ride the Bus + Pareidolia, Vampire
+  vs Steel Joker…), and destructive jokers (Ceremonial Dagger, Madness,
+  Stencil) carry a "Caution" line in the shop. Warnings never change the
+  score — they just stop a bad buy.
+- **Partner highlight**: while you hover a joker, the owned jokers it
+  combos with pulse gently on the board, so the names in the tooltip are
+  matched to cards by eye.
 - **Hover a joker you own** to see its active combos with the rest of your
-  lineup.
+  lineup — and, when your board is full, a "weakest combo piece" flag on
+  the joker contributing least to the build, so you know the natural cut
+  when something better shows up.
 - **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
@@ -32,6 +42,8 @@ recommends joker combos while you play:
   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.
+- **Progress tab**: completion bars for famous pairs fielded and themes
+  explored per group, plus the pairs fielded in the current run.
 - **Post-run combo recap**: the win and game-over screens list the famous
   pairs you fielded during that run.
 
@@ -49,7 +61,10 @@ recommends joker combos while you play:
 
 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.
+pairwise score of 2+ are listed in the tooltip, strongest first. The
+generic +1 counts once per shop candidate — not once per owned joker — so
+it can nudge a near-miss over the line but never carry a recommendation
+by itself; a pulsing card always has at least one nameable partner.
 
 ## Settings
 
@@ -58,9 +73,12 @@ 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
+- **Highlight combo partners on hover** — the on-board partner pulse.
-  keeping all the explanations, for players who want to learn the synergies
+- **Flag weakest joker when board is full** — the sell advisor line.
-  rather than be told what to buy.
+- **Learning mode** — hides the verdicts (pulse, "Strong pick!", the
+  weakest-joker flag) while keeping all the explanations and warnings, for
+  players who want to learn the synergies rather than be told what to buy.
+- **Touch mode** — larger advice text and buttons for phone screens.
 - **Recommendation threshold** — 2 (chatty) to 8 (only slam-dunk combos).
 
 Defaults live in `config.lua`.