belote-cli 4.9.6__tar.gz → 4.10.0__tar.gz

{belote_cli-4.9.6 → belote_cli-4.10.0}/.gitignore

@@ -147,3 +147,7 @@ cython_debug/
 
 # PyCharm
 .idea/
+
+# Editor swap files
+*.kate-swp
+*.swp

{belote_cli-4.9.6 → belote_cli-4.10.0}/CHANGELOG.md

@@ -5,6 +5,190 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.10.0] - 2026-11-01
+
+Verification pass over two external audit reports (every claim checked
+against the code), then the full follow-up: BelAtro becomes a true expansion
+of the core game, one shared round engine, the god functions split, and three
+features (Settings, achievement toasts, Daily Challenge). Refactors were
+verified with seeded whole-round fingerprints (BelAtro: 800 rounds across all
+bosses/jokers/flags; classic: 450 rounds incl. heavy undo) — byte-identical
+except the intended undo fix. Tests 1228 → 1286, coverage 79% → 83%.
+
+### Added
+- **Settings screen** (main menu → Settings), persisted to `settings.json` in
+  the config dir: AI difficulty (per seat), target, speed, theme, animations,
+  fast redraw, screen-reader hints, replay analysis, and expansion toggles
+  (BelAtro ghost recording). `BELOTE_*` env vars still override while set; the
+  CLI flags now override the saved values for one session.
+- **Achievement toasts:** unlocking an achievement pops a boxed toast (and a
+  screen-reader line) at the end of the round / game.
+- **Daily Challenge:** one date-seeded BelAtro run per day, identical for
+  everyone (fixed deck, starter shop pool, no endless), with a share code and
+  a local best-result record (`daily.json`).
+- **Screen-reader hints now announce declarations** (`a11y.announce_declaration`
+  existed but was never called).
+
+### Fixed
+- **Classic: undo during play re-ran the coinche flow** — the player was
+  re-prompted to coinche and the AI defenders were silently re-polled
+  (shifting their RNG) every time an undo resumed the play phase.
+- **BelAtro collection gallery** pinned the cursor to the top row (the list
+  was sliced from the selected item), hiding every item above it.
+- **BelAtro rules screen** called `hide_cursor()` without writing it (no-op).
+- **Le Divorce / La Trahison** could leave partner trust frozen at 0 if the
+  round aborted; the restore now runs in a `finally`.
+- **BelAtro: Sans Atout bid from the normal prompt became a pass.**
+  `UICallbacks.prompt_bid` filtered UI sentinels with `isinstance(res, str)`,
+  which also matched `SANS_ATOUT_BID` (the plain string `"sans_atout"`).
+- **L'Aristocrate ace payout ignored La Rupture / L'Anarchie.** Aces are now
+  credited via `compute_trick_winners` (new `_aces_won_by_team` helper) instead
+  of raw `trick_winner_seat` with the final trump.
+- **mypy was blind to every absolute `belote.*` import.** A stray empty
+  `src/__init__.py` made mypy name modules `src.belote.*`; with
+  `ignore_missing_imports` all `from belote.… import` resolved to `Any`.
+  Removed it (guarded by `tests/test_repo_layout.py`) and fixed the 9 errors
+  it was hiding (incl. a possible `None.lower()` in the BelAtro rules screen).
+- **Theme file ignored `XDG_CONFIG_HOME` / `%APPDATA%`** (hardcoded
+  `~/.config`, which also let the test suite write the real user config).
+- **Main menu flicker:** the 300ms steam animation no longer clears the whole
+  screen each tick; it repaints in place.
+- **Achievements are now visible** on the Statistics screen (they were
+  evaluated and saved but never shown).
+
+### Changed — architecture
+- **The core never imports BelAtro** (enforced by `tests/test_repo_layout.py`).
+  Boss/deck/voucher rule switches moved from BelAtro's `BossModifiers` +
+  `_joker_state` keys to a core `RuleVariants` (`belote/variants.py`,
+  `GameState.variants`). BelAtro's chips/mult/money/joker state moved off the
+  core `GameState` onto `belatro/core/state.py::BelatroState`, a subclass that
+  core transitions (now generic over `GameState` subclasses) carry along.
+  The stats screen, bid-hint line, I/V keys and main-menu modes are now
+  registration hooks wired from the entry point via `belatro/integration.py`.
+- **One round engine** (`belote/round_engine.py`): classic `gameflow` and
+  BelAtro `round_driver` are two `RoundPolicy` implementations of
+  `play_round`. Coinche level now lives on `state.coinche_level` in both modes.
+- **God functions split:** `process_event` (369 lines) → per-event handler
+  methods; `drive_round` (450) → a round context + phase functions;
+  `_play_blind` (344) → setup / boss / settlement helpers.
+- **Tests:** the 2037-line `test_belatro.py` split by topic (economy, score
+  accumulator, run state, jokers, shop, …); 2 duplicate tests removed; new
+  coverage for the round engine, headless classic rounds, the collection /
+  rules / shop screens, settings and the daily challenge.
+
+### Changed
+- AI / target / speed / theme moved from the main menu into Settings.
+- Shared key-alias table for the Unix and Windows readers; one
+  `ThemeManager.cycle()`; table-driven card art (byte-identical output);
+  `wrap_words` text helper; `BELOTE_NO_DIFF` read once instead of per frame.
+- One `legal_bids(state)` in `game.py` replaces four hand-rolled copies
+  (bid prompt, bid renderer, BelAtro joker hooks, partner legality gate).
+- One `deck.is_trump_card()` replaces the inline "trump suit or Déluge 7/8"
+  predicate in `deck.py`, `game.py`, `ai.py` and `round_driver.py`
+  (`_card_beats` keeps its Tout-Atout-exclusive variant, now commented).
+- New `belote/paths.py` owns data/config locations (was 5 copies; the BelAtro
+  ones fell back to the CWD on Windows without `%APPDATA%`).
+- Dix de Der uses `GLOBAL_CONFIG.LAST_TRICK_BONUS` everywhere (3 hardcoded 10s).
+- BelAtro history entries are built from typed `GameState`/`ScoringBreakdown`
+  instead of `object` + `getattr`.
+
+### Removed
+- `BelAtroAnnounce.score_popup` (slated for removal in 4.8) and its dead
+  overlay flag helpers.
+- `ScoreAccumulator.partner_jokers_double` / `TrustTrack.partner_jokers_double`
+  (deprecated since 3.5.0; `partner_tier` replaces them).
+- Dead code: `Seat.prev_seat`, `GameState.current_bidder`, `set_announced`,
+  `Config.ensure_stats_dir`, legacy `Config.CARD_*` / `MIN_TERM_*` /
+  `THEME_NAME`, `render.CARD_W/CARD_H/CARD_GAP/SIDE_COL_W`,
+  `ansi.save_cursor/restore_cursor/scroll_region`, unused HUD tables.
+
+## [4.9.7] - 2026-11-01
+
+Repo-wide audit: four parallel reviewers swept the classic engine, the
+classic UI/terminal layer, the BelAtro engine/run/progression code and the
+BelAtro items/UI; every finding was verified (most with a repro script) before
+fixing. Test count 1111 → 1228.
+
+### Fixed — test suite
+
+- **Tests no longer depend on (or write to) your real profile.** A new
+  `tests/conftest.py` points `HOME` / `XDG_CONFIG_HOME` / `XDG_DATA_HOME` at a
+  temp dir. The suite used to render with whatever theme the developer last
+  picked (the golden-frame hashes only passed with `moonlit_tavern` saved) and
+  `theme_manager.set_current()` rewrote `~/.config/belote/theme.json`.
+  Golden hashes re-pinned to the default `classic_green` theme.
+- Hardcoded `/home/mrrobot/belote/` paths in `tests/test_alt_screen_scroll.py`
+  replaced with a path relative to the test file.
+- `scripts/benchmark.py` is now `mypy --strict` clean.
+
+### Fixed — classic game
+
+- **L'Anarchie scored every trick with the end-of-round trump.** Tricks now
+  record the trump they were played under (`GameState.trick_trumps`) and final
+  scoring uses it (was wrong in ~99% of L'Anarchie rounds).
+- A **worthless carré of 7s/8s outranked the other team's sequences** and
+  wiped out their points. 0-point carrés no longer take part in declarations.
+- **Hard AI threw high off-suit cards to the opponents**, believing an
+  off-suit Ace beat a led King (normal and Tout Atout contracts).
+- **Tout Atout under L'Anarchie** silently became a one-suit game while still
+  being scored as Tout Atout; trump no longer rotates under TA.
+- Capots by the opponents counted as **your** capots in stats/achievements;
+  `first_capot` used `== 1`; "Triple Coup" read lifetime instead of session capots.
+- 6+ card sequences were labelled "0" in the round summary.
+
+### Fixed — terminal, UI and files
+
+- `--target 750` (non-preset) crashed the main menu.
+- Stats file: atomic writes; corrupt / wrong-shaped files no longer crash the
+  game (moved aside to `stats.json.bak`).
+- Unknown escape sequences leaked as keystrokes (F2 quit the game, Ctrl+→
+  played card 5, Delete typed `~`); Ctrl-C now quits.
+- In-game `FitAbortedError` (terminal too small → Q) exits cleanly.
+- Spacious HUD overflowed at 120–143 columns and scrolled the screen.
+- Game-over screen "staircased" (bare `\n` in raw mode).
+- Pressing T crashed on a read-only config dir; theme saves are atomic.
+- The game can now start on Windows (`termios` imported only on Unix); classic
+  stats honour `%APPDATA%`.
+- `BELOTE_A11Y=1` no longer scribbles over the game screen — see
+  DEVELOPMENT.md → Accessibility (`BELOTE_A11Y_OUT`).
+
+### Fixed — BelAtro
+
+- **All-pass deals ended the run**; they now redeal (and round-end jokers no
+  longer fire on the abandoned deal).
+- Partner bidding was backwards in round 1 (could take any suit except the
+  legal one; L'Économe could never bid).
+- L'Architecte "buy contract" crashed in round 1 after taking $10.
+- Le Traître / L'Agent Double replaced the boss's larger sabotage set.
+- L'Avocat's doubled target was ignored for payout, Le Puriste, trust and history.
+- Ghost runs: real seeds, seeded rounds, unique file names.
+- Corrupt / newer-schema `profile.json` no longer crashes launch.
+- Capots by EW counted as yours (unlocks, Pluto); Mercury/Pluto paid on EW contracts.
+- The shop offered jokers you already own (duplicates corrupted each other's
+  state); Le Jugement too.
+- Le Patriote, L'Illusionniste and La Sentinelle (P) mishandled Tout Atout;
+  Le Passeur paid $2 when North bid Sans Atout.
+- Shop cards: frame misaligned, long names overflowed, editions invisible.
+- Compact HUD: trust bar overwrote the synergy tooltip.
+- History overlay overflowed 90–99 column terminals.
+- An ante-8 victory continued into endless mode was recorded as a loss.
+
+### Changed — design calls
+
+- **Le Diable** now works: for one round North over-cuts with its lowest
+  winning trump whenever it can — even over your winning card.
+- **Sell jokers** in the shop with `S` for half their cost (same value as
+  La Tempérance). Corrupted jokers can't be sold; selling a Negative joker
+  returns its slot.
+- **Le Sergent** grows with the streak: +0.5, +1.0, +1.5, then +2.0 per trick
+  (was a flat +0.5 that ignored "consecutive").
+- **Le Tournoi** really offers you a coinche; theme flags no longer outlive
+  their ante. **Le Café**'s +25 chips is a petit-blind bonus, not permanent.
+- **Auto-Capot** (trust 9+) is no longer advertised — it was never implemented.
+- **Trust 3+ shows North's void suits** (`✦ Void: ♠♦`) instead of the whole
+  hand; seeing the full hand needs Le Carnet.
+- **Pluto** pays only when you took the contract and made it as a capot.
+
 ## [4.9.6] - 2026-06-01
 
 Follow-up bug-hunt, logic, and performance audit. Three parallel Explore agents

{belote_cli-4.9.6 → belote_cli-4.10.0}/DEVELOPMENT.md

@@ -2,6 +2,61 @@
 
 Welcome to the Belote development guide. This project is structured as a standard Python package.
 
+## Cheat Sheet
+
+Everything below assumes you're in the repo with the venv active:
+
+```bash
+cd ~/Projects/belote
+source .venv/bin/activate        # gives you `python`, `pip`, pytest, mypy, ruff
+```
+
+**1. Check everything is green (do this before every commit):**
+```bash
+PYTHONPATH=src python -m pytest -q && \
+  PYTHONPATH=src python -m mypy --strict src/ && \
+  python -m ruff check src/ tests/
+```
+
+**2. Push code to GitHub (no PyPI release):**
+```bash
+git status                       # see what changed — don't commit editor swap files
+git add <files>                  # or: git add -A   (after checking git status)
+git commit -m "what changed"
+git push origin master
+```
+
+**3. Release a new version to PyPI** (example: 4.9.7):
+```bash
+# a) bump the version in BOTH files (they must match):
+#      pyproject.toml          ->  version = "4.9.7"
+#      src/belote/__init__.py  ->  __version__ = "4.9.7"
+# b) add a "## 4.9.7" entry at the top of CHANGELOG.md
+# c) run the gates (step 1), then commit, tag and push:
+git add -A
+git commit -m "Release v4.9.7"
+git tag -a v4.9.7 -m "v4.9.7"
+git push origin master --tags
+# d) build, check and upload:
+rm -rf dist/ build/ *.egg-info/
+pipx run build --sdist --wheel
+pipx run twine check dist/*
+pipx run twine upload dist/*
+#    username: __token__
+#    password: your PyPI API token (starts with pypi-)
+#    make one at https://pypi.org/manage/account/token/
+```
+
+**4. Update the game installed with pipx** (from PyPI — https://pypi.org/project/belote-cli/):
+```bash
+pipx install belote-cli          # first time only
+pipx upgrade belote-cli          # after each release
+belote --version                 # confirm the new version
+```
+PyPI can take a minute to show a new upload. If `pipx upgrade` says you're
+already on the latest, wait a moment and retry, or force it with
+`pipx install --force belote-cli`.
+
 ## Setup
 
 1. **Clone the repository:**
@@ -10,15 +65,17 @@ Welcome to the Belote development guide. This project is structured as a standar
    cd belote
    ```
 
-2. **Create a virtual environment:**
+2. **Create a virtual environment** (use `python3` — many Linux distros don't
+   ship a bare `python` or `pip` outside a venv):
    ```bash
-   python -m venv .venv
+   python3 -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
    ```
 
-3. **Install in editable mode:**
+3. **Install in editable mode with the test + dev tools** (pytest, pytest-cov,
+   mypy, ruff):
    ```bash
-   pip install -e .
+   pip install -e ".[test,dev]"
    ```
 
 ## Running the Game
@@ -42,29 +99,31 @@ PYTHONPATH=src python3 -m belote.main
 
 ## Testing
 
-We use `pytest` for testing. Install it if you haven't already:
-```bash
-pip install pytest
-```
+We use `pytest` (installed by `pip install -e ".[test,dev]"` above).
+
+`tests/conftest.py` points `HOME`, `XDG_CONFIG_HOME` and `XDG_DATA_HOME` at a
+throwaway temp dir for the whole run, so the suite never reads or writes your
+real `~/.config/belote/theme.json`, stats or BelAtro saves, and always renders
+with the default theme (the golden-frame snapshot depends on that).
 
 Run tests:
 ```bash
 # Run all tests (Classic + BelAtro)
 PYTHONPATH=src pytest
 
-# Run only Classic Belote tests
-PYTHONPATH=src pytest tests/
+# Run only Classic Belote tests (tests/belatro/ lives inside tests/)
+PYTHONPATH=src pytest tests/ --ignore=tests/belatro
 
 # Run only BelAtro tests
 PYTHONPATH=src pytest tests/belatro/
 
 # Run a single test file
-PYTHONPATH=src pytest tests/test_game.py
-PYTHONPATH=src pytest tests/belatro/test_scoring.py
+PYTHONPATH=src pytest tests/test_game_logic.py
+PYTHONPATH=src pytest tests/belatro/test_round_driver.py
 
 # Run a single test by name
-PYTHONPATH=src pytest tests/test_game.py::test_play_card_legal
-PYTHONPATH=src pytest -k "test_scoring"
+PYTHONPATH=src pytest tests/test_render_golden.py::test_golden_frame_sha256
+PYTHONPATH=src pytest -k "capot"
 
 # Run with verbose output
 PYTHONPATH=src pytest -v
@@ -84,7 +143,7 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (1111 tests expected)
+# Full test suite (1228 tests expected)
 PYTHONPATH=src pytest
 ```
 
@@ -92,7 +151,7 @@ Run all gates before committing:
 
 ```bash
 PYTHONPATH=src python -m pytest --tb=short -q && \
-  python -m mypy --strict src/ && \
+  PYTHONPATH=src python -m mypy --strict src/ && \
   python -m ruff check src/ tests/
 ```
 
@@ -112,12 +171,42 @@ PYTHONPATH=src python scripts/benchmark.py
 
 Use these as a regression-detection floor for future changes.
 
+## Architecture: core game vs. BelAtro expansion
+
+- **The core never imports BelAtro.** `tests/test_repo_layout.py` enforces
+  it; only the composition root `belote/main.py` wires the expansion in via
+  `belote/belatro/integration.py` (menu modes, stats section, settings
+  toggle) and BelAtro installs its run-scoped hooks itself (history
+  override, bid hint, extension keys I/V).
+- **One round engine.** `belote/round_engine.py::play_round` owns the phase
+  order (bidding with all-pass handling → contract → tricks). Classic
+  (`gameflow.ClassicRound`) and BelAtro (`belatro/engine/round_driver.py::
+  _RoundContext`) are `RoundPolicy` implementations — change the round's
+  flow there, once.
+- **Rule variants are core.** Boss / deck / voucher effects that change how
+  Belote is played live on `GameState.variants` (`belote/variants.py`);
+  bosses only switch variants on.
+- **Expansion state rides on a subclass.** BelAtro's chips / mult / money /
+  joker state live on `belatro/core/state.py::BelatroState`. Core
+  transitions are generic over `GameState` subclasses and build states with
+  `replace()`, so the subclass survives every move.
+
 ## Accessibility
 
 Set `BELOTE_A11Y=1` to emit one-line plain-text descriptions of card plays,
 trick winners, locked contracts (4.6.5), declarations (4.6.5), and round
-results to stderr — readable by terminal screen readers (Orca, NVDA over
-WSL, VoiceOver via iTerm2).
+results — readable by terminal screen readers (Orca, NVDA over WSL,
+VoiceOver via iTerm2).
+
+Where the lines go (4.9.7 — writing them onto the full-screen game used to
+scroll and scramble the frame):
+
+- `BELOTE_A11Y_OUT=/path` — appended to that file or terminal device, e.g.
+  run `tty` in a second terminal and use its `/dev/pts/N`.
+- otherwise stderr, when it's redirected (`belote 2>a11y.txt`) or is a
+  different terminal from the game.
+- otherwise `~/.local/share/belote/a11y.log` (`%APPDATA%\belote\a11y.log` on
+  Windows) — follow it with `tail -f` in another terminal.
 
 The env var is read once at import; tests that mutate it must call
 `belote.a11y._refresh_enabled_from_env()` after the patch. Hook points live
@@ -127,8 +216,10 @@ run won/lost).
 
 ## Optional Runtime Flags
 
-The following environment variables enable opt-in features. Each is read
-once at startup; toggling mid-run has no effect.
+Players toggle these from the in-game **Settings** screen (`belote/settings.py`
+→ `settings.json`; `settings.apply()` pushes the values into the modules).
+The environment variables below still work and *override* the saved setting
+while set — handy for debugging and CI. Each is read once at startup.
 
 - `BELOTE_REPLAY=1` — after every Classic round, print a one-line summary
   of how often South's plays matched the Hard-AI's preferred line
@@ -136,8 +227,8 @@ once at startup; toggling mid-run has no effect.
   affects scoring. Backed by `src/belote/replay.py`.
 - `BELOTE_GHOST=1` — silently record every BelAtro run (seed, deck,
   bids, plays, round outcomes) to
-  `~/.local/share/belote/ghosts/<label>-<seed>.json`. The file is written
-  once when the run ends. Useful for sharing or replaying interesting
+  `~/.local/share/belote/ghosts/<label>-<seed>-<timestamp>.json`. The file
+  is written once when the run ends and never overwrites an earlier one. Useful for sharing or replaying interesting
   runs. Backed by `src/belote/belatro/ghost_run.py`.
 - `NO_COLOR=<any-non-empty>` — suppress truecolor SGR escapes from
   `fg()` / `bg()` per the [no-color.org](https://no-color.org/) spec.
@@ -164,9 +255,9 @@ once at startup; toggling mid-run has no effect.
 
 ## Releasing a New Version
 
-### Code-only update (push to GitHub without releasing a new PyPI version)
+The short version is in the [Cheat Sheet](#cheat-sheet) at the top. Details:
 
-If you're just iterating on code, fixing typos, updating docs, etc., and don't want to cut a new PyPI release yet:
+### Code-only update (push to GitHub without releasing a new PyPI version)
 
 ```bash
 git add <files>
@@ -174,32 +265,32 @@ git commit -m "<what changed>"
 git push origin master
 ```
 
-## Releasing a New Version (Manual)
+### Full release (GitHub + PyPI)
 
-1. **Bump the version** in BOTH `pyproject.toml` AND `src/belote/__init__.py`
+1. **Run all gates** (see Code Quality) — don't release a red build.
+2. **Bump the version** in BOTH `pyproject.toml` AND `src/belote/__init__.py`
    (they must stay in sync — `belote --version` / `belatro --version` read
    `__version__` while PyPI / pipx read `pyproject.toml`).
-2. **Add a CHANGELOG entry** at the top of `CHANGELOG.md`.
-3. **Clean stale build artifacts:**
+3. **Add a CHANGELOG entry** at the top of `CHANGELOG.md`.
+4. **Commit, tag and push:**
    ```bash
-   rm -rf dist/ build/ *.egg-info/
+   git add -A          # check `git status` first
+   git commit -m "Release vX.Y.Z"
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin master --tags
    ```
-4. **Build, validate, and upload:**
+5. **Clean stale build artifacts, then build, validate and upload:**
    ```bash
+   rm -rf dist/ build/ *.egg-info/
    pipx run build --sdist --wheel
    pipx run twine check dist/*
    pipx run twine upload dist/*
    ```
-
-   *Note: `twine upload` will prompt for your PyPI credentials or use your `~/.pypirc` file.*
-
-5. **Commit and tag in git:**
-   ```bash
-   git add pyproject.toml CHANGELOG.md
-   git commit -m "Release vX.Y.Z"
-   git tag -a vX.Y.Z -m "vX.Y.Z"
-   git push origin master --tags
-   ```
+   `twine upload` uses `~/.pypirc` if present; otherwise it prompts — enter
+   `__token__` as the username and a PyPI API token as the password.
+   PyPI never accepts the same version twice, so a botched upload means
+   bumping to the next patch version.
+6. **Update your own install:** `pipx upgrade belote-cli`.
 
 ## Performance measurement
 

{belote_cli-4.9.6 → belote_cli-4.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: belote-cli
-Version: 4.9.6
+Version: 4.10.0
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -113,14 +113,14 @@ belatro
        .-'``'|-._             )         _.-|
       /  .--.|   `''---...........---''`   |
      /  /    |           BelAtro           |
-     |  |    |       > Start Game <        |
-     |  |    |      AI:     < Hard >       |
-     |  |    |      Target: < 1000 >       |
-     |  |    |     Speed:  < Normal >      |
-     |  |    |  Theme:  < Classic Green >  |
+     |  |    |       Daily Challenge       |
+     |  |    |        > Start Game <       |
+     |  |    |           Settings          |
      |  |    |       Rules & History       |
-      \  \   |         Statistics          |
-       `\ `\ |            Quit             |
+     |  |    |          Statistics         |
+     |  |    |             Quit            |
+      \  \   |                             |
+       `\ `\ |                             |
          `\ `|                             |
          _/ /\                             /
         (__/  \                           /
@@ -157,8 +157,8 @@ belatro
 # Install in editable mode (recommended for development)
 pip install -e .
 
-# Or install from PyPI (once uploaded)
-pip install belote-cli
+# Or install from PyPI (recommended for playing)
+pipx install belote-cli      # update later with: pipx upgrade belote-cli
 
 # Play using the belote command
 belote
@@ -166,10 +166,26 @@ belote
 # Play the new Roguelite expansion
 belatro
 
-# Custom settings
+# One-off overrides of the saved settings (not persisted)
 belote --difficulty hard --target 500 --seed 123 --speed fast
 ```
 
+**Settings** live in the main menu's *Settings* screen and are saved to
+`settings.json` in your config directory (`$XDG_CONFIG_HOME/belote`, else
+`~/.config/belote`; `%APPDATA%\belote` on Windows): AI difficulty (per seat
+via Enter), target score, speed, theme, animations, fast redraw,
+screen-reader hints, post-round replay analysis and BelAtro ghost-run
+recording. The old `BELOTE_*` environment variables still work and override
+the saved value while set.
+
+**Daily Challenge** (main menu): one seeded BelAtro run per day, the same for
+everyone (fixed deck, date-derived seed, starter shop pool, no endless).
+The intro shows the day's number and a share code; your best result per day
+is kept locally.
+
+**Achievements** pop a toast the moment you unlock one and are listed on the
+Statistics screen.
+
 
 ## Controls
 
@@ -189,6 +205,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 **BelAtro (Roguelite):**
 - `1`-`5`: Inspect specific Jokers in the Shop
 - `C`: Open the Consumables tray in the Shop (use Tarots / Planets you've purchased)
+- `S` *(4.9.7)*: Sell a joker in the Shop for half its cost (corrupted jokers can't be sold)
 
 **Gameplay:**
 - `←` `→` or `↑` `↓` or **`W` `A` `S` `D`** *(4.5.0)*: Move selection
@@ -211,14 +228,14 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - **Collection (Almanac):** Persistent tracker to browse every Joker, Planet, and Voucher you've discovered across your runs.
 - **Full Boss Blind Suite:** All 21 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
 - **Multiplier Scoring:** Use items to stack Multipliers and reach scores in the millions.
-- **Partner Trust:** Build a relationship with your AI partner to unlock synergies.
+- **Partner Trust:** Build a relationship with your AI partner to unlock synergies. At trust 3+ the trust bar shows which suits North is void in (`✦ Void: ♠♦`); seeing North's full hand requires the Le Carnet voucher.
 - **Rich Terminal UI:** Full-screen themed felt table with detailed card graphics and "You" vs "Partner" terminology.
 - **Enhanced Hard AI**: Advanced void inference and 2-ply lookahead for critical tricks (Dix de Der).
 - **Customizable Themes:** Switch between thirteen color palettes (Classic Green, Dark Mode, Blue Velvet, Red Casino, Sepia Vintage, High Contrast, Colorblind, Forest Night, Moonlit Tavern, Royal Purple, Emerald Isle, Sunset Magma, Provence Lavande) using the `T` key during gameplay.
 - **Polished Felt Mat (3.9.4):** The trick mat now has a subtle vignette at its edges, a faint deterministic braille pip-dot texture (fabric-weave feel without intrusive glyphs), and — at standard/spacious terminal sizes — a decorative `╔═══◆═══...═══◆═══╗` outer frame with corner ornaments.
 - **Selection HUD (3.9.4):** Selecting a card in hand now paints a highlighted bar under it AND a centered `► A♠ — Trump ◄` readout below, color-coded by suit / trump / legality.
 - **Hand Sorting:** Strategic "play value" organization (honors grouped together) for better tactical awareness.
-- **Main Menu:** Simple single-player entry point with configurable AI difficulty, Target Score, and Speed.
+- **Main Menu:** Simple single-player entry point; AI difficulty, Target Score, Speed and Theme live in the Settings screen.
 - **Undo/Redo:** Press `Z` to undo your last move during bidding or play.
 - **Statistics:** unified global tracking of games played, win rates, best rounds, and BelAtro expansion milestones.
 - **Responsive Layout (3 tiers):** Three preset layouts — **compact** (80×32, fits 1366×768), **standard** (96×38), **spacious** (120×48+). The game picks the largest preset that fits your terminal on every render, so resizing mid-game adapts automatically; cards, side columns, and HUD verbosity all scale with the preset. Vertical centering pads tall terminals so the game never clings to the top.
@@ -264,7 +281,7 @@ belote/
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (1111 tests)
+├── tests/             # Comprehensive test suite (1228 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -279,14 +296,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **1111 tests** passing with 100% coverage on game-logic modules (4.9.6).
+Currently **1286 tests** passing with 100% coverage on game-logic modules (4.10.0).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 1111/1111 passed
+- **pytest**: 1228/1228 passed
 - **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
 - **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)