worker: same value-net tiebreak as the browser bot; refresh readme

Author: Shruichan

README.md

@@ -1,46 +1,61 @@
 # DuotrigordleBot
 
-Solver bot for [duotrigordle.com](https://duotrigordle.com) 
+A solver for [duotrigordle.com](https://duotrigordle.com) — 32 Wordle boards at
+once, 37 guesses. It scores every word against all the boards together and plays
+the best one.
 
-## Layout
+The extension and the web demo run the whole thing **in your browser** — no
+server, nothing to install past the extension itself.
 
-```
-data/        wordlists scraped from the live bundle
-core/        C++ solver — greedy / beam / endgame strategies
-server/      Python HTTP wrappers around the C++ worker
-extension/   Chrome MV3 extension that overlays suggestions on duotrigordle.com
-ml/          experiments: value net + turn-2 specialist training
-```
+- **Web demo + install steps:** https://shruichan.github.io/DuotrigordleBot/
+- **Extension:** load `extension/` unpacked (see below)
 
-## Build
+## How it plays
 
-```
-cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
-ninja -C build
-```
+Entropy across all unsolved boards + a bonus for words that are likely to solve
+a board outright. Near-tied candidates get re-ranked by a small value net that
+predicts how many guesses are left, which keeps the worst games short. Plus the
+usual endgame guards (distinct answers, a rhyme-trap override).
 
-Needs: cmake, ninja, OpenMP, GoogleTest, nlohmann_json. On Debian/Ubuntu:
+2000-game bench on the daily distribution:
 
-```
-sudo apt install cmake ninja-build libgtest-dev nlohmann-json3-dev
-```
+| | mean | max | 36s |
+|---|---|---|---|
+| tail-averse (default) | 33.76 | 35 | 0 |
+| lowest-mean greedy | 33.62 | 36 | 3 |
+
+100% solved, every game under the 37-guess daily limit. See `EXPERIMENTS.md` for
+the value-net / MCTS investigation and why ~33.6 is the floor.
 
-## Run
+## Layout
 
 ```
-python3 server/serve.py          # solver on http://127.0.0.1:8765
+web/         the JS engine (source of truth) + node tests
+extension/   self-contained Chrome MV3 extension (bundles the engine)
+docs/        GitHub Pages site — landing + in-browser solve demo
+data/        word lists + the trained value net
+core/        original C++ solver (greedy / endgame / mcts) + bench
+server/      optional local HTTP wrapper around the C++ worker
+ml/          training scripts (value net, turn-2 specialist)
 ```
 
-Load `extension/` as an unpacked Chrome extension, open duotrigordle.com.
+## Use the extension
 
-## Numbers
+1. Grab this repo and open `chrome://extensions`.
+2. Turn on Developer mode → "Load unpacked" → pick the `extension/` folder.
+3. Open duotrigordle.com. The overlay shows the next guess (first one takes a
+   couple seconds while the solver warms up).
 
-Greedy with answer-bonus, 500-game realistic (distinct-answer) bench:
+## Build the C++ core (optional)
 
-- 100% solve rate (under the Daily 37-guess threshold)
-- Mean: ~33.8 guesses
-- Range: 33–35
+Only needed for benching / the native worker:
 
+```
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+ninja -C build
+./build/dt_bench -n 2000 -S greedy --opener LITRE -a 300 --la-k 12 --la-exact \
+    --value-net data/value_net_20260527.bin
+```
 
-Headroom over greedy at turn 2 is ~0.35 guesses, the turn-2 specialist (ml/train_turn2.py) captures a small slice of
-that. Late game is essentially optimal under greedy.
+Needs cmake, ninja, OpenMP, GoogleTest, nlohmann_json
+(`sudo apt install cmake ninja-build libgtest-dev nlohmann-json3-dev`).

core/server/worker_main.cpp

@@ -1,6 +1,7 @@
 #include "feedback.hpp"
 #include "game_state.hpp"
 #include "strategy.hpp"
+#include "value_net.hpp"
 #include "wordlists.hpp"
 
 #include <nlohmann/json.hpp>
@@ -165,6 +166,18 @@ json process_request(const dt::Wordlists& w, const json& req) {
 
     dt::GreedyStrategy strat(w, alpha);
 
+    // Tail-averse value-net tie-break for auto mode (matches the browser bot):
+    // re-rank the near-tied top candidates by predicted remaining turns, which
+    // caps games at 35. Loaded once; skipped silently if the file is absent or
+    // in perfect mode (which must stay restricted to answer-only guesses).
+    static dt::ValueNet g_value_net;
+    static bool g_net_ready = g_value_net.load(std::string(DT_DATA_DIR) + "/value_net_20260527.bin");
+    if (g_net_ready && mode != "perfect") {
+        strat.set_value_net(&g_value_net);
+        strat.set_lookahead(12, 5);
+        strat.set_lookahead_exact(true);
+    }
+
     std::vector<int> active_idx;
     for (int b = 0; b < dt::NUM_BOARDS; ++b) {
         if (!state.boards[b].solved && !state.boards[b].candidates.empty()) {
@@ -199,6 +212,16 @@ json process_request(const dt::Wordlists& w, const json& req) {
         }
     }
 
+    // In auto mode, the headline pick is the strategy's actual decision (which
+    // applies the exact-V tie-break + endgame guards); promote it to the front.
+    if (g_net_ready && mode != "perfect" && !active_idx.empty() && state.guesses_used > 0) {
+        dt::WordIdx best = strat.choose_guess(state);
+        auto it = std::find(top.begin(), top.end(), best);
+        if (it != top.end()) top.erase(it);
+        top.insert(top.begin(), best);
+        if (static_cast<int>(top.size()) > top_k) top.resize(top_k);
+    }
+
     json suggestions = json::array();
     for (dt::WordIdx g : top) {
         json sug;