docs: cut v0.18.0 — launch-experience round + async winnable seeds

CHANGELOG.md gains a [0.18.0] section synthesising the 24 commits
since v0.17.0: the Restore prompt + auto-show Home picker launch
flow, MSSC-style picker (header chips, draw-mode chips, picture
tiles with FiraMono-covered glyphs, Today's Event callout), the
last solver hot path moving onto AsyncComputeTaskPool with
cancel-on-replace, "Won before" HUD chip, "Copy share link" Stats
button via arboard, the N-key flow finally routing through the
real Confirm/Cancel modal, Esc-on-modal layering fixes, and the
unified-3.0 Claude rule set adoption.

SESSION_HANDOFF.md (root) refreshed to reflect HEAD at
v0.17.0-24-gc497c31, the carryover punch list trimmed (items B
and C shipped, A partially shipped, D unchanged), and a new
Process notes section describing the test-discipline prune and
the smaller-port template the async hint work should follow.

Build: cargo clippy --workspace --all-targets -- -D warnings clean.
Tests: 1166 passing / 0 failing (one flake on
auto_save_writes_after_30_seconds reproduced clean on re-run;
passes in isolation).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitignore

@@ -1,4 +1,5 @@
 /target
+/.sccache-cache
 *.db
 *.db-shm
 *.db-wal

.sqlx/query-3a9bd2e51b2389da5b7e85f26806fcffa896748e0b589d216cf60827fc3857a9.json

@@ -0,0 +1,68 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT\n              r.id              AS \"id!: String\",\n              u.username        AS \"username!: String\",\n              r.seed            AS \"seed!: i64\",\n              r.draw_mode       AS \"draw_mode!: String\",\n              r.mode            AS \"mode!: String\",\n              r.time_seconds    AS \"time_seconds!: i64\",\n              r.final_score     AS \"final_score!: i64\",\n              r.recorded_at     AS \"recorded_at!: String\",\n              r.received_at     AS \"received_at!: String\"\n           FROM replays r\n           JOIN users   u ON u.id = r.user_id\n           ORDER BY r.received_at DESC\n           LIMIT ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "id!: String",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "username!: String",
+        "ordinal": 1,
+        "type_info": "Text"
+      },
+      {
+        "name": "seed!: i64",
+        "ordinal": 2,
+        "type_info": "Integer"
+      },
+      {
+        "name": "draw_mode!: String",
+        "ordinal": 3,
+        "type_info": "Text"
+      },
+      {
+        "name": "mode!: String",
+        "ordinal": 4,
+        "type_info": "Text"
+      },
+      {
+        "name": "time_seconds!: i64",
+        "ordinal": 5,
+        "type_info": "Integer"
+      },
+      {
+        "name": "final_score!: i64",
+        "ordinal": 6,
+        "type_info": "Integer"
+      },
+      {
+        "name": "recorded_at!: String",
+        "ordinal": 7,
+        "type_info": "Text"
+      },
+      {
+        "name": "received_at!: String",
+        "ordinal": 8,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      true,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "3a9bd2e51b2389da5b7e85f26806fcffa896748e0b589d216cf60827fc3857a9"
+}

.sqlx/query-5bc1984044bc792c2e9577a159ca22789469df14cb25144451f37e8cdad8165c.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT replay_json FROM replays WHERE id = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "replay_json",
+        "ordinal": 0,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "5bc1984044bc792c2e9577a159ca22789469df14cb25144451f37e8cdad8165c"
+}

.sqlx/query-6a36a96faa9d9b423aae3b72b0c049a1489b67ca2361581b2300bb4ee0bc9e2f.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO replays (\n              id, user_id, seed, draw_mode, mode, time_seconds, final_score,\n              recorded_at, received_at, replay_json\n           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 10
+    },
+    "nullable": []
+  },
+  "hash": "6a36a96faa9d9b423aae3b72b0c049a1489b67ca2361581b2300bb4ee0bc9e2f"
+}

ARCHITECTURE.md

@@ -47,11 +47,11 @@ Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, tar
 ### Design Principles
 
 - **Offline first.** The local file is always the source of truth. Sync is additive, never destructive.
-- **Pure core.** All game logic lives in a dependency-free Rust crate with no Bevy, no network, and no I/O. This keeps it fully unit-testable and portable.
-- **No panics in game logic.** Every state transition returns `Result<_, MoveError>`. Panics are only acceptable in startup/configuration code.
 - **One language, one repo.** The game client, sync client, shared types, and sync server are all Rust crates in a single Cargo workspace.
 - **Plugin-based Bevy architecture.** Each major feature is a Bevy `Plugin`. Systems are small and single-purpose. Cross-system communication uses Bevy `Event`s.
 
+Pure-core, no-panics-in-game-logic, and UI-first-interaction constraints are enforced by CLAUDE.md §2.1, §2.3, and §3.3 respectively — those are the canonical statements; this file describes the design that motivates them.
+
 ---
 
 ## 2. Workspace Structure
@@ -67,11 +67,11 @@ solitaire_quest/
 ├── Dockerfile                  # Multi-stage server build
 ├── docker-compose.yml          # Server + Caddy reverse proxy
 │
-├── assets/                     # Assets embedded at compile time via include_bytes!()
+├── assets/                     # Loaded at runtime via AssetServer (audio is embedded via include_bytes!())
 │   ├── cards/
-│   │   ├── faces/{rank}_{suit}.png  # 52 individual card faces (120×168, generated by solitaire_assetgen)
-│   │   └── backs/back_0.png – back_4.png    # placeholder patterns
-│   ├── backgrounds/bg_0.png – bg_4.png      # placeholder textures
+│   │   ├── faces/{RANK}{SUIT}.png   # 52 card faces — rendered from hayeah/playing-cards-assets SVGs (MIT)
+│   │   └── backs/back_0.png – back_4.png    # back_0 = generated default back; back_1–4 are generated patterns
+│   ├── backgrounds/bg_0.png – bg_4.png      # generated textures
 │   ├── fonts/main.ttf          # FiraMono-Medium (170K, OFL)
 │   └── audio/
 │       ├── card_deal.wav
@@ -132,7 +132,7 @@ Owns:
 - `SyncProvider` trait — implemented by `SolitaireServerClient`
 
 ### `solitaire_engine`
-**Dependencies:** `bevy`, `bevy_kira_audio`, `solitaire_core`, `solitaire_data`.
+**Dependencies:** `bevy`, `kira`, `solitaire_core`, `solitaire_data`.
 
 All Bevy-specific code. Structured as a collection of Plugins that `solitaire_app` registers.
 
@@ -144,7 +144,7 @@ Owns:
 - All Bevy UI screens (Home, Stats, Achievements, Settings, Profile)
 - Audio playback systems
 - Sync status display
-- Card, background, and font asset loading (embedded via `include_bytes!()` — no `AssetServer` dependency)
+- Card, background, and font asset loading via Bevy `AssetServer` (audio is the lone exception — embedded via `include_bytes!()` in `audio_plugin.rs`)
 
 ### `solitaire_server`
 **Dependencies:** `solitaire_sync`, `axum`, `sqlx`, `jsonwebtoken`, `bcrypt`, `tower-governor`, `tracing`, `tokio`, `dotenvy`.
@@ -235,20 +235,22 @@ Done
 
 ### Bevy Plugins
 
-| Plugin | Key | Responsibility |
+The "Shortcut" column lists optional keyboard accelerators. Every action in this table must also be reachable from a visible UI control (button, menu item, on-screen affordance) per the UI-first design principle in §1; the shortcut is a power-user convenience, not the sole entry point.
+
+| Plugin | Shortcut | Responsibility |
 |---|---|---|
 | `CardPlugin` | — | Card entity spawning, sprite management, drag-and-drop |
 | `TablePlugin` | — | Pile markers, background, layout calculation |
-| `FontPlugin` | — | Embeds FiraMono-Medium font at compile time; exposes `FontResource` handle |
+| `FontPlugin` | — | Loads FiraMono-Medium via `AssetServer` at startup; exposes `FontResource` handle |
 | `AnimationPlugin` | — | Slide, flip, win cascade, toast animations |
 | `FeedbackAnimPlugin` | — | Shake, settle, and deal-stagger animations |
 | `AutoCompletePlugin` | Enter | Executes auto-complete when the HUD badge is lit |
-| `AudioPlugin` | — | Sound effect and music playback via bevy_kira_audio |
+| `AudioPlugin` | — | Sound effect and music playback via kira |
 | `InputPlugin` | — | Keyboard and mouse input routing |
 | `CursorPlugin` | — | Custom cursor sprite during drag |
 | `SelectionPlugin` | — | Keyboard-driven card selection |
 | `GamePlugin` | N | Core game state resource, new-game flow, win/game-over overlays |
-| `HudPlugin` | — | Score, move counter, timer, auto-complete badge |
+| `HudPlugin` | — | Score, move counter, timer, auto-complete badge, and the top-right action button bar (Undo / Pause / Help / New Game). Each button fires the same request event the corresponding hotkey does. |
 | `StatsPlugin` | S | Stats overlay and persistence |
 | `ProgressPlugin` | — | XP/level system, persistence |
 | `AchievementPlugin` | A | Unlock evaluation, toast events, persistence |
@@ -296,7 +298,7 @@ struct CardImageSet {
     backs: [Handle<Image>; 5],       // indexed by selected_card_back setting
 }
 
-// Project-wide font handle (FiraMono-Medium embedded at compile time)
+// Project-wide font handle (FiraMono-Medium loaded via AssetServer at startup)
 struct FontResource(Handle<Font>);
 
 // Pre-loaded background PNG handles
@@ -713,11 +715,14 @@ pub struct AchievementDef {
 | `speed_and_skill` | ??? | Win < 90s without undo | Yes | Card back #4 |
 | `comeback` | ??? | Win after 3+ stock recycles | Yes | Background #4 |
 | `zen_winner` | ??? | Win in Zen Mode | Yes | Badge |
+| `cinephile` | Cinephile | Watch a saved replay all the way through | No | — |
 
 ### Evaluation Timing
 
 Achievement conditions are evaluated by `AchievementPlugin` on every `GameWonEvent` and `StateChangedEvent`. The plugin calls `solitaire_core::check_achievements()` which returns a `Vec<AchievementDef>` of newly unlocked achievements. The plugin then fires `AchievementUnlockedEvent` for each, which the toast and persistence systems handle independently.
 
+A small number of achievements are *event-driven* rather than condition-driven: their `AchievementDef::condition` always returns `false` and their unlock is written from a dedicated observer system instead. `cinephile` is the canonical example — it unlocks when `ReplayPlaybackState` transitions from `Playing` to `Completed` (a saved replay watched to its natural end). The Stop button transitions `Playing → Inactive` directly without entering `Completed`, so manual aborts do not unlock the achievement.
+
 ---
 
 ## 12. Progression System
@@ -751,7 +756,7 @@ Levels 11+:   level = 10 + floor((total_xp - 5000) / 1000)
 
 ## 13. Audio System
 
-Audio uses `bevy_kira_audio`. All sound files are `.wav`.
+Audio uses `kira`. All sound files are `.wav`.
 
 | File | Trigger |
 |---|---|
@@ -762,7 +767,7 @@ Audio uses `bevy_kira_audio`. All sound files are `.wav`.
 | `win_fanfare.wav` | Game won |
 | `ambient_loop.wav` | Looping background music |
 
-Volume is controlled by two independent sliders in Settings (`sfx_volume`, `music_volume`), each stored in `Settings` and applied as `bevy_kira_audio` channel volumes.
+Volume is controlled by two independent sliders in Settings (`sfx_volume`, `music_volume`), each stored in `Settings` and applied as `kira` channel volumes.
 
 Audio systems listen for Bevy events and never block the game thread.
 
@@ -772,11 +777,13 @@ Audio systems listen for Bevy events and never block the game thread.
 
 ### Rendering approach
 
-Cards are Bevy `Sprite` entities with `Handle<Image>` from `CardImageSet`. Face-up cards use one of 52 individual face PNGs selected by `faces[suit][rank]` — rank and suit are baked into each image and no `Text2d` overlay is spawned. Face-down cards use `backs/back_N.png` indexed by `settings.selected_card_back`. `Text2d` labels are only used as a fallback when `CardImageSet` is absent (e.g. tests with `MinimalPlugins`). `CardImageSet` is populated at startup from `include_bytes!()` — no `AssetServer`.
+Cards are Bevy `Sprite` entities with `Handle<Image>` from `CardImageSet`. Face-up cards use one of 52 individual face PNGs selected by `faces[suit][rank]` — rank and suit are baked into each image and no `Text2d` overlay is spawned. Face-down cards use `backs/back_N.png` indexed by `settings.selected_card_back`. `Text2d` labels are only used as a fallback when `CardImageSet` is absent (e.g. tests with `MinimalPlugins`). `CardImageSet` is populated at startup by `card_plugin::load_card_images` via `AssetServer::load()`.
 
-Backgrounds are Bevy `Sprite` entities with `Handle<Image>` from `BackgroundImageSet`. `BackgroundImageSet` is populated at startup from `include_bytes!()`.
+Backgrounds are Bevy `Sprite` entities with `Handle<Image>` from `BackgroundImageSet`. `BackgroundImageSet` is populated at startup by `table_plugin::load_background_images` via `AssetServer::load()`.
 
-The font `FiraMono-Medium` is embedded via `include_bytes!()` at startup by `FontPlugin` and exposed as `FontResource` for use by all UI and text systems.
+The font `FiraMono-Medium` is loaded via `AssetServer::load("fonts/main.ttf")` at startup by `FontPlugin` and exposed as `FontResource` for use by all UI and text systems.
+
+All three loaders take `Option<Res<AssetServer>>` so they degrade cleanly under `MinimalPlugins` in tests: when the server is absent, `CardImageSet`/`BackgroundImageSet` are inserted with empty handle slots and the plugins fall back to `Text2d` rank+suit overlays and solid-colour board backgrounds. The `assets/` directory must ship alongside the binary.
 
 The `assets/` directory layout:
 
@@ -1004,5 +1011,7 @@ Using `axum::test` and an in-memory SQLite database:
 | `SyncProvider` trait, not `SyncBackend` match arms | `SyncPlugin` stays backend-agnostic and testable; new backends can be added without touching the plugin | 2026-04-20 |
 | Dropped WebDAV backend | Redundant once the self-hosted server exists; removing it reduces surface area and simplifies settings UI | 2026-04-20 |
 | Dropped GPGS backend | Redundant with the self-hosted server; adds JNI complexity for no user-visible benefit on the target platforms | 2026-04-28 |
-| PNG assets embedded via `include_bytes!()` | Using `Image::from_buffer()` in startup systems rather than `AssetServer::load()` keeps the binary self-contained and eliminates runtime file-not-found errors | 2026-04-29 |
-| FiraMono-Medium font embedded via `include_bytes!()` | Exposed through `FontResource`; avoids runtime font loading errors on headless systems and ensures consistent text rendering across all platforms | 2026-04-29 |
+| Card, background, and font assets loaded via `AssetServer` | Reverses the earlier embed-via-`include_bytes!()` decision: PNGs and TTFs are loaded at runtime so artwork can be swapped (e.g. alternate card backs, themed backgrounds) without a recompile, and binary size stays small. Loaders take `Option<Res<AssetServer>>` and fall back gracefully under `MinimalPlugins`. The `assets/` directory must ship alongside the binary. | 2026-04-29 |
+| Audio assets remain embedded via `include_bytes!()` | Audio files are small, change rarely, and the embedded path eliminates a class of runtime-load errors during gameplay; the asset-pipeline reversal does not extend to audio | 2026-04-29 |
+| Card art swapped from xCards (LGPL-3.0) to hayeah/playing-cards-assets (MIT) | Public-release readiness. The previous xCards art carried LGPL relinking obligations that complicate a single-binary distribution; hayeah's set derives from the public-domain `vector-playing-cards` line-art and is permissively MIT-licensed. CREDITS.md license summary collapsed to MIT + OFL-1.1. The default card back is original work in this project's midnight-purple palette. | 2026-05-01 |
+| Runtime SVG card-theme system (`CARD_PLAN.md`) | User-supplied themes need to ship SVG sources so they can rasterise at any resolution on the player's hardware; baking PNGs at build time only would lock theme installation to the developer. The pipeline (usvg → resvg → tiny-skia) rasterises once per (theme, target size) at load time and caches the resulting `Image`, so the runtime cost is paid once, not per frame. The bundled default theme ships via `embedded://`; user themes via `themes://` rooted at `user_theme_dir()`. | 2026-05-01 |

CHANGELOG.md

@@ -0,0 +1,760 @@
+# Changelog
+
+All notable changes to Solitaire Quest are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
+project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.18.0] — 2026-05-06
+
+The launch-experience round. The engine used to drop the player on a
+silent default Classic deal whether they had unfinished work or not;
+v0.18.0 replaces that with two stacked decision points — a Restore
+prompt for in-progress saves, then an MSSC-style Home / mode picker
+that surfaces Daily / Zen / Challenge / Time Attack as picture tiles
+with live stats. The same round closes the last solver-on-main-thread
+hot path (winnable-only seed selection moves to
+`AsyncComputeTaskPool`), wires "Copy share link" into Stats, lights a
+"Won before" HUD chip on re-deals of beaten seeds, and tidies the
+unified-3.0 rule set across CLAUDE.md / CLAUDE_SPEC.md /
+CLAUDE_WORKFLOW.md / CLAUDE_PROMPT_PACK.md.
+
+### Added
+
+- **Restore prompt on launch** (`3c7a0eb`). When `game_state.json`
+  holds an in-progress game (`move_count > 0`, not won), the engine
+  now seeds `GameStateResource` with a fresh deal and holds the saved
+  game in a new `PendingRestoredGame` resource. After the splash
+  clears, a "Welcome back" modal offers **Continue** (Enter / C /
+  click) or **New game** (N / click). Fresh-deal saves
+  (`move_count == 0`) skip the prompt and load directly.
+- **Save preservation while the prompt is unanswered** (`f863d85`).
+  Both `save_game_state_on_exit` and `auto_save_game_state` consult
+  `PendingRestoredGame` first: if it still holds a pending saved
+  game, that's what gets persisted (or the auto-save is skipped),
+  so exiting before answering the prompt no longer overwrites the
+  meaningful save with the placeholder fresh deal.
+- **Home / mode picker auto-shows on launch** (`dd63261`). The mode
+  picker was only reachable via **M** during gameplay; players who
+  hadn't discovered the hotkey never saw the Daily / Zen / Challenge
+  / Time Attack entry points after the splash cleared. `HomePlugin`
+  gains an `auto_show_on_launch` flag (default true) and a
+  one-shot `LaunchHomeShown` gate. Skips when the Restore prompt is
+  on screen so Welcome-back still takes precedence.
+- **MSSC-style Home picker — header / chips / score chips / draw
+  mode** (`ae40a1d`). Player-stats header strip (Level / XP /
+  Lifetime Score, compact-formatted as `1.2M` / `12.3K` / `1,234`)
+  acts as a clickable shortcut to Profile. Draw-mode chip row above
+  the mode cards lets the player flip Draw 1 / Draw 3 from the
+  picker itself; persists `settings.json` and respawns the modal so
+  the active state repaints cleanly. Per-mode best-score / streak
+  chips on each card; hidden on a 0 best so a fresh profile doesn't
+  read "Best 0" everywhere.
+- **Today's Event callout on the Daily card** (`b73d246`). "Today,
+  May 6" date line plus the server-fetched goal (when SyncPlugin is
+  wired). Once today's daily is recorded as completed, the date
+  flips to `Today, May 6 • Done` in `ACCENT_PRIMARY` so the picker
+  reads as a reward state rather than a TODO.
+- **Picture-tile mode cards** (`9fe650f` + glyph-picking follow-ups
+  `40d6e0a`, `c30b04e`, `d065d49`). Mode cards become a wrapping
+  2-up grid (`FlexWrap::Wrap`, tiles 48 % wide, `min_height: 180px`)
+  with a centred Unicode-glyph centrepiece per tile. Final glyph set
+  picked from FiraMono-Medium's actual coverage: ♣ Classic, ◆ Daily,
+  ○ Zen, ▲ Challenge, → TimeAttack. `ACCENT_PRIMARY` when the mode is
+  unlocked, `TEXT_DISABLED` when locked. Centrepiece is a `Text` node
+  for now — when real per-mode artwork lands, swap to `Image` without
+  touching tile layout, focus order, or chip rendering.
+- **Solver-vetted seed selection on `AsyncComputeTaskPool`**
+  (`d489e7a`). Closes the worst-case 6 s UI stall on a New Game
+  click with "Winnable deals only" enabled. New `PendingNewGameSeed`
+  resource holds the in-flight `Task<u64>` plus the original
+  request's `mode` / `confirmed` flags. `poll_pending_new_game_seed`
+  runs `.before(GameMutation)` and replays a synthetic
+  `NewGameRequestEvent` once the task resolves — the player sees no
+  extra-frame visual lag. Cancel-on-replace: a fresh
+  `NewGameRequestEvent` while a task is in flight drops the old
+  task, letting Bevy's `Task` Drop cancel cooperatively at the next
+  await point.
+- **"Won before" HUD indicator** (`bdac754`). When the current
+  deal's `(seed, draw_mode, mode)` triple matches an entry in the
+  rolling `ReplayHistory`, the HUD's tier-2 context row shows
+  **✓ Won before** in `STATE_SUCCESS`. Cleared on win (the on-screen
+  victory cue is enough) and on first-time deals. New
+  `HudWonPreviously` marker driven by a separate
+  `update_won_previously` system; gracefully no-ops in headless
+  tests that don't load `StatsPlugin`.
+- **"Copy share link" Stats button** (`540869c`). End-to-end replay
+  sharing on a server-backed sync backend:
+  `sync_plugin::push_replay_on_win` spawns the upload on
+  `AsyncComputeTaskPool` and stores the handle in
+  `PendingReplayUpload` (drops any in-flight predecessor — the most
+  recent win is what the player wants the link for);
+  `poll_replay_upload_result` writes `<server>/replays/<id>` to
+  `LastSharedReplayUrl` on success; the Stats overlay's action bar
+  gains a button that writes the URL to the OS clipboard via
+  `arboard` and surfaces a "Copied: \<url\>" toast. URL is in-memory
+  only — sharing must happen within the session of the win.
+- **Empty-state copy + onboarding hints** (`56e2e6f`). Leaderboard
+  empty state: two-tier "Be the first on the leaderboard." headline
+  + body invite. Achievements panel: first-launch hint above the
+  grid until the first unlock. Volume hotkeys (`[` / `]`) now emit
+  an `InfoToastEvent` with the new percentage so off-panel
+  adjustments give visible feedback (previously silent).
+- **Enter dismisses the Win Summary and starts a fresh deal**
+  (`17e0737`). The post-win modal's "Play Again" was click-only;
+  keyboard-only players had to reach for the mouse to leave the
+  celebration screen. The button label gains a trailing return-key
+  glyph so the keyboard path is discoverable on first sight.
+- **`N` opens the real Confirm/Cancel modal** (`93660c2`). The old
+  "Press N again" double-tap pattern was a UI-first violation (only
+  continuation was another keystroke). `N` now fires
+  `NewGameRequestEvent::default()` directly; `handle_new_game`'s
+  active-game check spawns the existing `ConfirmNewGameScreen`. The
+  HUD button already routed through the same modal — keyboard and
+  mouse paths are unified. `Shift+N` keeps the keyboard power-user
+  bypass (`confirmed: true`).
+
+### Changed
+
+- **Settings row layout** (`a4bc063`). All five
+  slider/toggle row helpers (volume × 2, tooltip delay, time-bonus
+  multiplier, replay-move interval, generic toggle) restructured to
+  a label-spacer-cluster layout (`width: 100%`, label gets
+  `flex-grow: 1`, controls cluster sits flush right). Stable across
+  varying value-text widths ("0.80" → "1.00", "Instant" vs "1.5 s")
+  and narrow windows.
+- **Docs adopt the unified-3.0 rule set** (`f2f30c8`). `CLAUDE.md`
+  grows from a 114-line pointer doc to a 571-line rulebook (hard
+  global constraints §2, engine rules §3, asset rules §4, code
+  standards §5, build + verification §6, git workflow §7, the ASK
+  BEFORE list §8, Context Injection System §14). New companions:
+  `CLAUDE_SPEC.md` (formal architecture spec — crate dependency
+  graph, data ownership, state-machine invariants, sync merge /
+  server contracts, validation checklist),
+  `CLAUDE_WORKFLOW.md` (two-agent Builder/Guardian pipeline with
+  hard-fail patterns), `CLAUDE_PROMPT_PACK.md` (task-type
+  templates). Three duplicate rule passages removed across
+  `CLAUDE_SPEC.md` and `ARCHITECTURE.md`.
+- **Test discipline pruning** (`a49a340`). Removed 43 low-value
+  tests across `solitaire_data` and `solitaire_core` (default-value
+  tests, serde-derive round-trips on plain structs, single-field
+  clamp tests, near-duplicates, constant-equals-itself tests). None
+  pinned a behaviour contract or a regression on a real bug. Future
+  agent briefs request tests for behaviour contracts or real-bug
+  regressions, not a count of N.
+
+### Fixed
+
+- **Esc on a modal no longer opens Pause underneath** (`08b006f`).
+  A single Esc press on Confirm New Game / Restore / Home /
+  Onboarding / Settings used to both close the modal and spawn the
+  Pause overlay on top in the same frame. `toggle_pause` now skips
+  when any non-Pause `ModalScrim` is in the world; the HUD-button
+  path is gated too. The four modal queries are bundled into a
+  `PauseModalQueries` `SystemParam` to stay under Bevy's
+  16-parameter cap.
+- **Esc dismisses Home / accepts the Restore-prompt default**
+  (`d48b948`). Both screens previously ignored Esc, leaving the
+  player no keyboard-only escape after the previous fix. Home: Esc
+  behaves like Cancel (despawns the modal, keeps the underlying
+  default deal). Restore: Esc maps to Continue (preserves the saved
+  game, matching how the primary action already advertises Enter).
+- **Esc dismisses the topmost modal when Profile stacks on Home**
+  (`9aa0dd2`). Clicking the Home header chip opens Profile on top
+  of Home; Esc used to close Home (because
+  `handle_home_cancel_button` fired with no awareness of layered
+  modals) and leave Profile orphaned over the game.
+  `profile_plugin` now splits P/button (toggle) from Esc
+  (close-only); `handle_home_cancel_button` skips its Esc branch
+  when any other `ModalScrim` exists.
+- **Restore-prompt resolution suppresses Home auto-show**
+  (`b7c3a49`). Resolving the Welcome-back prompt cleared
+  `PendingRestoredGame` and despawned the modal, but the
+  launch-time Home auto-show then fired the next frame and stacked
+  itself over the player's chosen path. `LaunchHomeShown` becomes
+  `pub` so `handle_restore_prompt` flips it to `true` after either
+  resolution; **M** still re-opens the picker on demand.
+- **Game timers freeze while the Home picker is up** (`c497c31`).
+  The HUD's elapsed-time counter ticked from the moment the default
+  Classic deal landed at startup, even though the auto-show Home
+  picker was still up — the player saw "0:11" before they had
+  chosen a mode. `tick_elapsed_time` and `advance_time_attack` now
+  also gate on the absence of `HomeScreen`, mirroring their
+  existing `PausedResource` check.
+- **Popover rows stay visible regardless of action-bar fade**
+  (`cc63532`). Opening Modes / Menu showed a solid dark-purple
+  block in the top-right with no readable content — the action-bar
+  auto-fade was matching the popover rows by their shared
+  `ActionButton` marker and dropping their alpha to the
+  cursor-position-based fade value (typically 0). New `PopoverRow`
+  marker on rows in `spawn_modes_popover` / `spawn_menu_popover`;
+  `apply_action_fade` excludes them via `Without<PopoverRow>`.
+
+### Stats
+
+- 1166 passing tests (was 1208 at v0.17.0 close — 43 net removals
+  from the test-discipline prune plus 1 net-new test from the
+  async-seed work, no behaviour regressions).
+- Zero clippy warnings under `--workspace --all-targets -- -D warnings`.
+
+## [0.17.0] — 2026-05-06
+
+A short follow-up round on top of v0.16.0: the H-key hint is no
+longer a heuristic guess but the actual best first move suggested by
+the v0.15.0 solver, and the in-engine replay player now has a
+player-tunable playback rate.
+
+### Added
+
+- **Replay-rate slider** in Settings → Gameplay. Tunes
+  `replay_move_interval_secs` from 0.10 s to 1.00 s in 0.05 s steps;
+  default 0.45 s. `tick_replay_playback` reads the value from
+  `SettingsResource` per frame so the slider takes effect on the
+  next playback tick — no restart required.
+
+### Changed
+
+- **Solver-driven hints.** Pressing **H** used to surface a
+  heuristic-best move (foundation moves preferred, then
+  tableau-to-tableau by depth-of-flip-revealed). It now asks the
+  v0.15.0 solver for the actual provably-best first move via the
+  new `solitaire_core::solver::try_solve_with_first_move` /
+  `try_solve_from_state` APIs. When the solver returns inconclusive
+  (rare deals where the bound runs out before a result), the old
+  heuristic remains the fallback. Median 2 ms per H press.
+
+### Stats
+
+- 1208 passing tests (was 1196 at v0.16.0 close).
+- Zero clippy warnings under `--workspace --all-targets -- -D warnings`.
+
+## [0.16.0] — 2026-05-06
+
+A modal-feel polish round. Every overlay screen now scrolls when its
+content overflows the 800×600 minimum window, every clickable button
+shows a hand cursor on hover, keyboard focus lands on the primary
+button on the same frame the modal opens, and read-only modals
+dismiss when the player clicks the scrim outside the card.
+
+### Added
+
+- **Pointer cursor on hover** for every interactive `Button` entity
+  (modal buttons, HUD action bar, mode-launcher cards, settings
+  toggles, Stats selectors). `update_cursor_icon` gains a fourth
+  branch sitting between Grabbing (active drag) and Grab
+  (draggable card hover): when no drag is active and any
+  `Interaction::Hovered`/`Pressed` button is detected, the window
+  cursor swaps to `SystemCursorIcon::Pointer`. A pure
+  `pick_cursor_icon` helper makes the priority logic
+  unit-testable.
+- **Click-outside-to-dismiss** for the six read-only modals: Stats,
+  Achievements, Help, Profile, Leaderboard, Home. New
+  `ScrimDismissible` marker on `ModalScrim` opts a modal in;
+  `dismiss_modal_on_scrim_click` runs in `Update`, despawns the
+  topmost dismissible scrim on a left-mouse press whose cursor
+  lands on the scrim and outside every `ModalCard`. Bevy's
+  hierarchy despawn cascades to the card and children.
+  Settings, Onboarding, Pause, Forfeit confirm, and Confirm New
+  Game intentionally don't opt in — they carry unsaved or
+  destructive state.
+
+### Fixed
+
+- **Modal content scrolls when it overflows** (Achievements, Help,
+  Stats, Profile, Leaderboard). Each modal's body Node now
+  carries `Overflow::scroll_y()` plus a `max_height` constraint
+  (`Val::Vh(70.0)` for most, `Val::Vh(50.0)` for the
+  leaderboard's variable-length ranking section) and a marker
+  component (`AchievementsScrollable`, `HelpScrollable`,
+  `StatsScrollable`, `ProfileScrollable`,
+  `LeaderboardScrollable`). A sibling `scroll_*_panel` system
+  per modal routes `MouseWheel` events into the body's
+  `ScrollPosition`. Mirrors the existing `SettingsPanelScrollable`
+  pattern. Home modal intentionally not scrolled — its five
+  mode cards + Cancel are sized to fit at 800×600 by design.
+- **Modal focus arrives on the same frame the modal opens.**
+  Previously `attach_focusable_to_modal_buttons` and
+  `auto_focus_on_modal_open` ran in `Update` alongside arbitrary
+  click-handlers that spawn modals; with no ordering edge,
+  Bevy's deferred `Commands` queued the new entities but the
+  attach system couldn't see them on the same tick. Both systems
+  moved to `PostUpdate` so the schedule boundary itself supplies
+  the sync point — `FocusedButton` is always populated before
+  `app.update()` returns. The very next Tab/Enter press lands on
+  a populated resource instead of wasting itself moving focus
+  from None to the primary.
+
+### Stats
+
+- 1196 passing tests (was 1178 at v0.15.0 close).
+- Zero clippy warnings under `--workspace --all-targets -- -D warnings`.
+
+## [0.15.0] — 2026-05-02
+
+In-engine replay playback, the Klondike solver + "Winnable deals
+only" toggle, a 19th achievement, rolling replay history, and a
+significant build-time / binary-size win from disabling Bevy's
+default audio stack.
+
+### Added
+
+- **In-engine replay playback** for the Stats overlay's Watch Replay
+  button. New `ReplayPlaybackPlugin` runs a state machine
+  (Inactive / Playing / Completed) that resets the live game to the
+  recorded deal and ticks through `replay.moves` at
+  `REPLAY_MOVE_INTERVAL_SECS` (0.45 s) firing the canonical
+  `MoveRequestEvent` / `DrawRequestEvent` per recorded move.
+  Recording is suppressed during playback so replays don't re-record
+  themselves.
+- **Replay overlay banner** (`ReplayOverlayPlugin`) anchored to the
+  top of the window during playback. Shows "Replay" label, "Move N
+  of M" progress, and a Stop button. Z-order leaves modals
+  (Settings, Pause, Help) free to render on top so the player can
+  adjust audio mid-replay.
+- **Rolling replay history** at `<data_dir>/replays.json` capped at
+  8 entries. Replaces the single-slot `latest_replay.json` (legacy
+  file is migrated forward on first launch via
+  `migrate_legacy_latest_replay`). Stats overlay gains a Prev / Next
+  selector and a "Replay N / M" caption so the player can revisit
+  older wins.
+- **"Cinephile" achievement** (#19). Unlocks the first time
+  `ReplayPlaybackState` transitions Playing → Completed (i.e. the
+  replay played out to its end without the player pressing Stop).
+  Stop transitions Playing → Inactive directly so it doesn't count.
+- **Klondike solver** in `solitaire_core::solver`. Iterative-DFS
+  with memoisation on a 64-bit canonical state hash, two budget
+  knobs (move_budget + state_budget) for pathological cases, and a
+  three-state `SolverResult` (Winnable / Unwinnable / Inconclusive).
+  Median solve time 2 ms; pathological inconclusives cap near
+  120 ms. Pure logic — `solitaire_core` keeps no Bevy or I/O.
+- **"Winnable deals only" toggle** in Settings → Gameplay (default
+  off). When on, `handle_new_game` walks seed N, N+1, N+2, …
+  through `try_solve` until it finds Winnable or Inconclusive,
+  capped at `SOLVER_DEAL_RETRY_CAP` (50) attempts. Daily
+  challenges, replays, and explicit-seed requests bypass the
+  solver — only random Classic deals are gated.
+
+### Changed
+
+- **Bevy default-feature trim** (`bevy = { default-features = false,
+  features = [...] }` in workspace Cargo.toml) drops 51 transitive
+  crates including the `bevy_audio` → rodio → cpal 0.15 + symphonia
+  chain that the project doesn't use (kira handles audio directly).
+  The retained feature list is curated to exactly what the engine
+  uses; `solitaire_wasm` is unaffected because it doesn't depend on
+  bevy.
+
+### Stats
+
+- 1178 passing tests (was 1134 at v0.14.0 close).
+- Zero clippy warnings under `--workspace --all-targets -- -D warnings`.
+
+## [0.14.0] — 2026-05-02
+
+Two threads land in v0.14.0: the second half of the post-v0.12.0 UX
+candidate list (theme thumbnails, daily-challenge calendar, Time Attack
+auto-save, per-mode bests, time-bonus multiplier) plus a **major new
+feature** — the replay pipeline (record → upload → web viewer). Three
+Quat-reported bugs from a smoke-test round shipped alongside.
+
+### Added
+
+- **Theme-picker thumbnails** in Settings → Cosmetic. Each theme chip
+  renders a small Ace-of-Spades + back preview pair via the existing
+  `rasterize_svg` path. Cached per theme in a new
+  `ThemeThumbnailCache`. Themes that lack a preview SVG fall back to
+  a transparent placeholder rather than crashing.
+- **14-day daily-challenge calendar** in the Profile modal. Horizontal
+  row of dots showing the trailing two weeks; today's dot is ringed
+  in `ACCENT_PRIMARY`, completed days fill `STATE_SUCCESS`, missed
+  days fill `BG_ELEVATED`. Caption above the row reads "Current
+  streak: N · Longest: M".
+- **Time Attack session auto-save** to `<data_dir>/time_attack_session.json`,
+  atomic .tmp + rename. 30-second auto-save while a session is active,
+  plus on `AppExit`. Sessions whose 10-minute window expired in real
+  time while the app was closed are discarded on load. Classic, Zen,
+  and Challenge already auto-saved correctly via `game_state.json` —
+  Time Attack was the only mode missing session-level persistence.
+- **Per-mode best-score and fastest-win readouts** in the Stats screen.
+  `StatsSnapshot` gains six `#[serde(default)]` fields (Classic / Zen
+  / Challenge × best_score + fastest_win_seconds). Stats screen renders
+  a "Per-mode bests" section between the primary cell grid and
+  progression. Lifetime totals continue to roll all modes together.
+- **Time-bonus multiplier slider** in Settings → Gameplay (0.0–2.0,
+  0.1 steps, default 1.0, "Off" label at zero). Cosmetic only —
+  multiplies the time-bonus shown in the win modal but does NOT
+  affect achievement unlock thresholds (those still use the raw
+  unmultiplied score).
+- **Win-replay recording + storage.** Every move during a successful
+  game appends to a `RecordingReplay` resource; on `GameWonEvent`
+  the recording freezes into a `Replay` (seed + draw_mode + mode +
+  score + time + ordered move list) and persists to
+  `<data_dir>/latest_replay.json` atomically. Single-slot — overwrites
+  on every win.
+- **"Watch replay" button** in the Stats overlay. Shows the latest
+  win's caption and surfaces a button that loads the replay (button
+  fires an `InfoToastEvent` describing the replay; full in-engine
+  playback is deferred to a future build).
+- **Replay upload + fetch endpoints** on the server. `POST /api/replays`
+  accepts a `Replay` JSON; `GET /api/replays/:id` returns it. JWT-gated
+  with the existing auth middleware. Engine uploads winning replays
+  automatically when the player has cloud sync configured.
+- **`solitaire_wasm` crate** — new workspace member compiling
+  replay-relevant `solitaire_core` types to WebAssembly so a
+  browser can re-execute a replay client-side. No-std-friendly
+  surface; `wasm-bindgen` glue.
+- **Web replay viewer** served from the Solitaire server.
+  `GET /replays/:id` returns HTML + CSS + the wasm bundle that
+  fetches the replay JSON, rasterises a deal from the seed, and
+  animates the recorded moves.
+- **Card flight animations on the web side** so the browser viewer
+  reads as a real game replay rather than a static dump.
+
+### Fixed
+
+- **Multi-card lift validation.** `solitaire_core::rules::is_valid_tableau_sequence`
+  rejects a moved stack whose adjacent cards don't form a descending
+  alternating-colour run. Previously a player could lift any
+  multi-card selection and drop it as long as the bottom landed
+  legally. Wired into `move_cards`'s tableau-destination branch.
+- **Softlock detection.** `has_legal_moves` rewritten to walk every
+  potential move source (every stock card, every waste card, the
+  face-up top of every tableau column) and check it against every
+  foundation and every tableau. Previously the heuristic
+  early-returned `true` whenever stock had cards — players got
+  stuck in unwinnable end-states with no end-game screen.
+  `GameOverScreen` now actually fires for true softlocks. Quat's
+  exact reproduction case is pinned by a new test.
+- **Deal-tween information leak.** New-game now snaps every card
+  sprite to the stock pile position before writing
+  `StateChangedEvent`, so all 52 cards animate from a single point
+  during the deal. Previously the sprites started from their
+  previous-game positions, briefly revealing the prior deal.
+
+### Documentation
+
+- `SESSION_HANDOFF.md` refreshed for the Quat smoke-test round
+  including investigation findings on solver decisions and
+  dependency duplicates.
+
+### Stats
+
+- 1134 passing tests (was 1053 at v0.13.0 close).
+- Zero clippy warnings under `--workspace --all-targets -- -D warnings`.
+
+## [0.13.0] — 2026-05-02
+
+Third UX iteration round on top of v0.12.0. Six handoff candidates
+shipped — three small polish items, three larger interaction
+features (theme-aware backs, full keyboard play, right-click power
+shortcut). Plus two code-review fixes (font handling unified,
+sccache wiring removed).
+
+### Added
+
+- **Tooltip-delay slider** in Settings → Gameplay. `tooltip_delay_secs`
+  ranges [0.0, 1.5] in 0.1 s steps; "Instant" label when zero.
+  `Settings.tooltip_delay_secs` round-trips through serialise/deserialise
+  with `#[serde(default)]`. The hover-delay comparison in
+  `ui_tooltip` reads from `SettingsResource` with the existing
+  `MOTION_TOOLTIP_DELAY_SECS` as the test-fixture fallback.
+- **Win-streak fire animation.** New `WinStreakMilestoneEvent` fires
+  from `stats_plugin` when `win_streak_current` crosses any of
+  [3, 5, 10] (only the threshold crossing — not every subsequent
+  win). The HUD streak readout scale-pulses 1.0 → 1.20 → 1.0 over
+  `MOTION_STREAK_FLOURISH_SECS` (0.6 s).
+- **Score-breakdown reveal on the win modal.** Replaces the single
+  "Score: N" line with a per-component reveal (Base / Time bonus /
+  No-undo bonus / Mode multiplier / Total). Rows fade in over
+  `MOTION_SCORE_BREAKDOWN_FADE_SECS` (0.12 s) staggered by
+  `MOTION_SCORE_BREAKDOWN_STAGGER_SECS` (0.15 s). Honours
+  `AnimSpeed::Instant` by spawning all rows fully visible.
+- **Card backs follow the active theme.** `theme.ron`'s `back` slot
+  now actually drives the face-down sprite. Active-theme back
+  rasterises alongside the faces and supersedes the legacy
+  `back_N.png` picker. The picker remains as a fallback for themes
+  that don't ship a back, and the Settings UI surfaces a caption
+  ("Active theme provides its own back") + dimmed swatches when
+  the override is in effect.
+- **Keyboard-only drag-and-drop.** Tab cycles draggable card stacks,
+  Enter "lifts" the focused stack, arrow keys (or Tab) cycle the
+  legal-destination targets only, Enter confirms, Esc cancels. A
+  new `KeyboardDragState` resource models the two-mode flow without
+  changing the existing `SelectionState` contract. Mutual exclusion
+  with mouse drag uses a sentinel `DragState.active_touch_id =
+  KEYBOARD_DRAG_TOUCH_ID` (u64::MAX) so neither pipeline can
+  trample the other.
+- **Right-click radial menu.** Hold right-click on a face-up card →
+  a small ring of icons appears at the cursor with one entry per
+  legal destination. Release over an icon → fires
+  `MoveRequestEvent`; release in dead space, Esc, or left-click
+  cancels. Skips the drag motion entirely. New `RadialMenuPlugin`
+  owns the flow; co-exists with the existing `RightClickHighlight`
+  pile-marker tint.
+
+### Fixed
+
+- **Font handling consolidated to bundled-only.** Code-review
+  feedback: the SVG rasteriser previously mixed
+  `load_system_fonts` + bundled FiraMono + a lenient resolver,
+  which made card text rendering depend on host fontconfig. Picked
+  option (a) and applied it across both layers — `font_plugin` now
+  embeds `assets/fonts/main.ttf` via `include_bytes!()` and
+  registers it with `Assets<Font>`; `svg_loader::shared_fontdb`
+  loads only the bundled bytes; the new `bundled_font_resolver`
+  ignores the SVG's `font-family` request and always returns the
+  single bundled face. A parse failure aborts with a clear error
+  ("bundled FiraMono failed to parse — binary is corrupt").
+
+### Removed
+
+- **Project-level sccache wiring.** Code-review feedback: sccache
+  shouldn't be a per-project build dependency. Cargo's incremental
+  cache already covers the single-project case, and forcing
+  `rustc-wrapper = "sccache"` workspace-wide meant every contributor
+  had to install it. `.cargo/config.toml` deleted entirely; plain
+  `cargo build` now works without setup.
+
+### Documentation
+
+- `help_plugin` controls reference gains a "Mouse" section covering
+  double-click auto-move, right-click highlight, and the new
+  hold-RMB radial.
+- `help_plugin` also gains a "Keyboard drag" section for the new
+  Tab/Enter/Arrows/Esc flow.
+- Onboarding slide 3 picks up a `Tab → Enter` row referencing the
+  full keyboard drag path.
+
+### Stats
+
+- 1053 passing tests (was 1031 at v0.12.0 close).
+- Zero clippy warnings under `--workspace --all-targets -- -D warnings`.
+
+## [0.12.0] — 2026-05-02
+
+UX feel polish round on top of v0.11.0. Six small-but-tangible
+improvements that make the play surface feel more responsive,
+forgiving, and discoverable, plus the doc refresh that should have
+ridden along with v0.11.0.
+
+### Added
+
+- **Foundation completion flourish.** When a King lands on a
+  foundation (Ace-through-King for that suit), a brief celebration
+  fires: King card scale-pulses 1.0 → 1.15 → 1.0 over 0.4 s, the
+  foundation marker tints `STATE_SUCCESS` for the first half then
+  fades, and a synthesised C6→E6→G6 bell ping plays (~240 ms,
+  octave above `win_fanfare`'s root so the fourth completion + win
+  cascade layer cleanly). New `FoundationCompletedEvent { slot,
+  suit }` carries the trigger so future systems can hook in.
+- **Drag-cancel return tween.** Illegal drops glide each dragged
+  card back to its origin slot over 150 ms with a quintic ease-out
+  curve (`MotionCurve::Responsive`, zero overshoot — reads forgiving
+  rather than jittery). The audio cue (`card_invalid.wav`) still
+  fires for negative feedback. Right-click and double-click invalid
+  paths still use `ShakeAnim` since there's no motion to interpolate.
+- **Focus ring breathing.** The keyboard focus ring's alpha modulates
+  with a 1.4 s sin curve over [0.65, 1.0] of its native value so the
+  indicator catches the eye on focus changes without competing with
+  gameplay. Honours `AnimSpeed::Instant` by reverting to the static
+  outline for reduced-motion users.
+- **First-win achievement onboarding toast.** After the player's
+  very first win, a one-shot info toast surfaces "First win! Press
+  A to see your achievements." `Settings.shown_achievement_onboarding`
+  persists the seen state so the cue never re-fires (legacy
+  `settings.json` files load to `false` via `#[serde(default)]`).
+- **Mode Launcher digit shortcuts.** Pressing M opens the Home modal
+  (the Mode Launcher); inside it, pressing 1–5 launches each mode
+  directly without needing Tab + Enter. Locked modes (Zen, Challenge,
+  Time Attack at level < 5) are silent no-ops. Modal-scoped — digit
+  keys outside the launcher fire nothing.
+
+### Fixed
+
+- **Card aspect ratio matches hayeah SVGs.** `CARD_ASPECT` 1.4 →
+  1.4523 to match the bundled artwork's natural 167.087 × 242.667
+  dimensions. Cards previously rendered ~3.6 % vertically squashed.
+  The vertical-budget math in `compute_layout` uses `CARD_ASPECT`
+  algebraically so the worst-case-tableau-fits-on-screen guarantee
+  adapts automatically.
+
+### Documentation
+
+- **README refresh** with v0.11.0+ features (card themes, HUD
+  overhaul, drag feel, unlocked foundations) and a corrected controls
+  table — the previous table inverted Z/U for undo and listed H for
+  help when F1 is the binding.
+- **CHANGELOG.md** added (this file), covering v0.9.0–v0.12.0 with
+  Keep a Changelog 1.1.0 conventions.
+
+### Stats
+
+- 1007 passing tests (was 982 at v0.11.0).
+- Zero clippy warnings under `--workspace --all-targets -- -D warnings`.
+
+## [0.11.0] — 2026-05-02
+
+The biggest release since 0.10.0. Headline threads: a runtime card-theme
+system, an HUD restructure that reclaims the play surface, and a round of
+UX feel polish surfaced by smoke testing.
+
+### Added
+
+- **Runtime card-theme system** (CARD_PLAN phases 1–7).
+  - Bundled default theme ships in the binary via `embedded://` — 52
+    [hayeah/playing-cards-assets](https://github.com/hayeah/playing-cards-assets)
+    SVGs (MIT) plus a midnight-purple `back.svg` as original work.
+  - User themes live under `themes://` rooted at `user_theme_dir()`. Drop
+    a directory containing `theme.ron` + 53 SVGs and the registry picks
+    it up on next launch.
+  - Importer at `solitaire_engine::theme::import_theme(zip)` validates
+    archives (20 MB cap, zip-slip rejection, manifest validation, every
+    SVG round-tripped through the rasteriser) and atomically unpacks.
+  - Picker UI in **Settings → Cosmetic**; selection persists as
+    `selected_theme_id` and propagates to live sprites.
+- **Reserved HUD top band** (64 px) so cards no longer crowd the score
+  readout or action buttons; layout's `top_y` shifts down accordingly.
+- **Action-bar auto-fade** — buttons fade out when the cursor leaves the
+  band, fade back in when it returns. Lerp at ~167 ms.
+- **Visible drop-target overlay during drag** — a soft fill plus 3 px
+  outline drawn ABOVE stacked cards for every legal target (full fanned
+  column for tableaux, card-sized for foundations and empty tableaux).
+  Replaces the previously invisible pile-marker tint.
+- **Card drop shadows** — every card casts a neutral 25 % black shadow
+  with a 4 px halo; cards in the active drag set switch to a lifted
+  shadow (40 % alpha, larger offset, bigger halo).
+- **Stock remaining-count badge** — small `·N` chip at the top-right of
+  the stock pile so the player can see how close they are to a recycle.
+  Hides when the stock empties.
+
+### Changed
+
+- **Foundations are unlocked.** `PileType::Foundation(Suit)` →
+  `Foundation(u8)` (slot 0..3). The claimed suit is derived from the
+  bottom card via `Pile::claimed_suit()` — no separate field, no
+  claim-stuck-after-undo bugs. Any Ace lands in any empty slot, and the
+  slot then claims that suit. `next_auto_complete_move` prefers a
+  claim-matched slot before falling back to the first empty slot for
+  Aces. Empty foundation markers render as plain placeholders (no
+  "C/D/H/S").
+- **HUD selection label** and **hint toast** read `claimed_suit()` and
+  fall through to "Foundation N" / "move to foundation" only when the
+  slot is empty.
+
+### Fixed
+
+- **`shared_fontdb` now bundles FiraMono.** The hayeah SVGs reference
+  `Bitstream Vera Sans` and `Arial` by name. On minimal Linux installs
+  / fresh Wayland sessions / chroots where neither is installed AND the
+  CSS-generic aliases don't resolve, card rank/suit text vanished. The
+  bundled font is loaded into fontdb and pinned as every CSS generic's
+  target so the resolver always lands on something real. Surfaced when
+  a second-machine pull rendered cards without glyphs.
+- **Theme asset path resolution** — `AssetPath::resolve` (concatenates)
+  → `resolve_embed` (RFC 1808 sibling resolution). Was producing paths
+  like `…/theme.ron/hearts_4.svg` and failing to load every face SVG.
+- **Sync exit log spam** — `push_on_exit` silently no-ops on
+  `LocalOnlyProvider`'s `UnsupportedPlatform` instead of warn-spamming
+  every shutdown.
+- **usvg font-substitution warn spam** — custom `FontResolver.select_font`
+  appends `Family::SansSerif` and `Family::Serif` to every query so
+  unmatched named families silently fall through.
+
+### Migration
+
+- **In-progress saves invalidated.** `GameState.schema_version` bumped
+  1 → 2; pre-v2 `game_state.json` files silently fall through to "fresh
+  game on launch." Stats, progress, achievements, and settings live in
+  separate files and are unaffected.
+
+### Stats
+
+- 982 passing tests (was 819 at v0.10.0).
+- Zero clippy warnings under `--workspace --all-targets -- -D warnings`.
+
+## [0.10.0] — 2026-04-29
+
+PNG art pipeline plus a major dependency pass. The first release where
+the binary shipped with bundled artwork.
+
+### Added
+
+- **52 individual card face PNGs** generated via `solitaire_assetgen`.
+- **Custom font** (FiraMono-Medium) loaded via `AssetServer` at startup
+  through the new `FontPlugin`.
+- **Card backs and backgrounds** upgraded to 120×168 with richer
+  patterns.
+- **Ambient audio loop** wired through the kira mixer.
+- **Arch Linux PKGBUILDs** for the game client and sync server (under
+  the separate `solitaire-quest-pkgbuild` directory).
+- **Workspace README, CI workflow, migration guide.**
+
+### Changed
+
+- **Bevy 0.15 → 0.18** workspace migration.
+- **kira 0.9 → 0.12** audio backend migration.
+- **Edition 2024**, MSRV pinned to **Rust 1.95**.
+- **rand 0.9** upgrade.
+- **Card rendering** moved from `Text2d` overlay to PNG-backed
+  `Sprite` with face/back atlases; `Text2d` retained as a headless
+  fallback when `CardImageSet` is absent (tests under MinimalPlugins).
+- **Asset pipeline** switched from `include_bytes!()` for PNGs/TTFs to
+  runtime `AssetServer::load()` so artwork can be swapped without a
+  recompile. Audio remains embedded.
+- **Removed Google Play Games Services sync backend** — redundant with
+  the self-hosted server.
+
+### Fixed
+
+- **Server JWT secret** loaded at startup (was lazy, surfaced as
+  intermittent 500s).
+- **Daily-challenge race** in the server's seed-generation path.
+- **Rate limiter** switched to `SmartIpKeyExtractor` so the limit
+  applies per real client IP rather than per upstream proxy.
+- **Touch input** uses `MessageReader<TouchInput>` (Bevy 0.18 rename).
+- **Sync push/pull races** in async task scheduling.
+- **Hot-path allocations** reduced in card-rendering systems.
+- **Conflict report coverage** added for sync merge edge cases.
+
+### Stats
+
+- 819 passing tests at tag time.
+
+## [0.9.0] — 2026-04-28
+
+Initial public-tagged release. Established the workspace structure
+(`solitaire_core` / `_sync` / `_data` / `_engine` / `_server` / `_app` /
+`_assetgen`), the modal scaffold via `ui_modal`, the design-token system
+in `ui_theme`, and the four-tier HUD layout. Foundations were
+suit-locked at this point; cards rendered as `Text2d` rank/suit overlays
+with no PNG artwork yet.
+
+### Added
+
+- Klondike core (Draw One / Draw Three modes).
+- Progression system (XP, levels, 18 achievements, daily challenge,
+  weekly goals, special modes at level 5).
+- Self-hosted sync server (Axum + SQLite + JWT auth).
+- All 12 overlay screens migrated to the `ui_modal` scaffold with real
+  Primary/Secondary/Tertiary buttons.
+- Animation upgrades: `SmoothSnap` slide curves, scoped settle bounce,
+  deal jitter, win-cascade rotation.
+- Splash screen, focus rings (Phases 1–3), tooltips infrastructure +
+  HUD/Settings/popover applications, achievement integration tests,
+  destructive-confirm verb unification, leaderboard error/idle states,
+  first-launch empty-state polish, hit-target accessibility fix,
+  CREDITS.md, persistent window geometry, mode-launcher Home repurpose,
+  client-side sync round-trip integration tests.
+
+[Unreleased]: https://github.com/funman300/Rusty_Solitaire/compare/v0.16.0...HEAD
+[0.16.0]: https://github.com/funman300/Rusty_Solitaire/compare/v0.15.0...v0.16.0
+[0.15.0]: https://github.com/funman300/Rusty_Solitaire/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/funman300/Rusty_Solitaire/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/funman300/Rusty_Solitaire/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/funman300/Rusty_Solitaire/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/funman300/Rusty_Solitaire/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/funman300/Rusty_Solitaire/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/funman300/Rusty_Solitaire/releases/tag/v0.9.0

CLAUDE.md

@@ -1,111 +1,571 @@
-# Solitaire Quest — Claude Code Instructions
+# CLAUDE.md
 
-See @ARCHITECTURE.md for full project design, crate responsibilities, data models, and API reference.
+version: unified-3.0
 
 ---
 
-## Project Layout
+# 0. Role of This File
 
-```text
-solitaire_core/    # Pure Rust game logic — NO Bevy, NO network, NO I/O
-solitaire_sync/    # Shared API types — NO Bevy, serde/uuid/chrono only
-solitaire_data/    # Persistence + SyncProvider trait + server client
-solitaire_engine/  # Bevy ECS systems, components, plugins
-solitaire_server/  # Axum sync server binary
-solitaire_app/     # Thin binary entry point
-assets/            # Source assets — embedded at compile time via include_bytes!()
+This document defines:
+
+* **Execution rules (what Claude must do)**
+* **System constraints (what Claude must never violate)**
+* **Operational architecture (how code is structured)**
+
+For full system design details:
+→ `ARCHITECTURE.md` (authoritative source of truth)
+
+This file overrides all conversational assumptions.
+
+---
+
+# 1. System Architecture (Authoritative Mapping)
+
+## 1.1 Crates
+
+```text id="crate_map"
+solitaire_core/    # PURE logic (no IO, no Bevy, deterministic)
+solitaire_sync/    # Shared API + merge logic
+solitaire_data/    # Persistence + sync client
+solitaire_engine/  # Bevy ECS + UI + gameplay orchestration
+solitaire_server/  # Axum backend (optional sync layer)
+solitaire_app/     # Entry binary
+assets/            # Runtime assets (except audio)
 ```
 
 ---
 
-## Build & Test Commands
+## 1.2 Architecture Source of Truth
 
-```bash
-# Dev run (fast compile via dynamic linking)
-cargo run -p solitaire_app --features bevy/dynamic_linking
+* Full system design: `ARCHITECTURE.md`
+* This file NEVER redefines system design
+* This file ONLY enforces behavior
 
-# Release build
-cargo build --workspace --release
+---
 
-# All tests — MUST pass before any commit
+# 2. Hard Global Constraints (NON-NEGOTIABLE)
+
+These override all other instructions.
+
+## 2.1 Core Determinism
+
+* `solitaire_core` MUST:
+
+  * be deterministic
+  * be side-effect free
+  * never depend on Bevy / IO / async
+
+---
+
+## 2.2 Sync Isolation
+
+* `solitaire_sync`:
+
+  * no Bevy
+  * no IO
+  * no engine dependencies
+* merge logic must be pure functions only
+
+---
+
+## 2.3 Error Policy
+
+* NO `unwrap()`
+* NO `panic!()` in runtime/game logic
+* All state transitions:
+
+```rust id="err_model"
+Result<T, MoveError>
+```
+
+---
+
+## 2.4 Threading Rules
+
+* Sync must run on `AsyncComputeTaskPool`
+* NEVER block Bevy main thread
+
+---
+
+## 2.5 Persistence Rules
+
+* atomic writes only:
+
+  * write `.tmp`
+  * rename atomically
+* no partial state writes allowed
+
+---
+
+## 2.6 Security Rules
+
+* credentials ONLY via `keyring`
+* NEVER store secrets in:
+
+  * files
+  * logs
+  * source code
+
+---
+
+## 2.7 Sync System Rules
+
+* All sync backends implement:
+
+```rust id="sync_trait"
+trait SyncProvider
+```
+
+* `SyncPlugin` MUST be backend-agnostic
+* NEVER match on backend inside ECS systems
+
+---
+
+# 3. Engine Rules (Bevy Layer)
+
+## 3.1 ECS Design
+
+* systems = single responsibility
+* communication = Events only
+* shared state = Resources only
+* per-entity state = Components only
+
+---
+
+## 3.2 Game State Authority
+
+* ONLY `GameStateResource` can mutate game state
+* UI systems MUST NOT directly modify core logic
+
+---
+
+## 3.3 UI-First Constraint (CRITICAL)
+
+Every player action MUST:
+
+* have a visible UI control
+* NOT rely solely on keyboard shortcuts
+
+Keyboard shortcuts are:
+→ optional accelerators only
+
+---
+
+## 3.4 Layout System
+
+* recompute on `WindowResized`
+* no fixed resolution assumptions
+
+---
+
+# 4. Asset System Rules
+
+## 4.1 Runtime Assets (AssetServer)
+
+Loaded via:
+
+* `CardImageSet`
+* `BackgroundImageSet`
+* `FontResource`
+
+Includes:
+
+* cards
+* backgrounds
+* fonts
+
+---
+
+## 4.2 Embedded Assets
+
+Only audio:
+
+```text id="audio_rule"
+include_bytes!()
+```
+
+---
+
+## 4.3 Test Compatibility Rule
+
+All asset loaders MUST accept:
+
+```rust id="asset_fallback"
+Option<Res<AssetServer>>
+```
+
+Must degrade gracefully under `MinimalPlugins`.
+
+---
+
+# 5. Code Standards
+
+## 5.1 Error Handling
+
+* use `thiserror`
+* no `Box<dyn Error>` in libraries
+
+---
+
+## 5.2 Public API Rules
+
+* prefer `Into<T>` over concrete types
+* all public items require doc comments
+
+---
+
+## 5.3 Derive Order
+
+```rust id="derive_order"
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+```
+
+---
+
+## 5.4 Performance Rules
+
+* NO `clone()` in hot paths
+* profile before optimizing
+
+---
+
+## 5.5 SQL Rules
+
+* ONLY `sqlx::query!`
+* NO raw SQL strings
+
+---
+
+# 6. Build & Verification Rules
+
+These are mandatory before ANY commit.
+
+```bash id="build_rules"
 cargo test --workspace
-
-# Lint — MUST pass clean (zero warnings)
 cargo clippy --workspace -- -D warnings
-
-# Run sync server locally
-cargo run -p solitaire_server
-
-# Check a single crate
-cargo test -p solitaire_core
-cargo clippy -p solitaire_core -- -D warnings
 ```
 
 ---
 
-## Hard Rules
+# 7. Git Workflow Rules
 
-- `solitaire_core` and `solitaire_sync` must never gain Bevy or network dependencies.
-- No `unwrap()` or `panic!()` in game logic. All state transitions return `Result<_, MoveError>`.
-- Audio assets are embedded at compile time using `include_bytes!()` in `audio_plugin.rs`. Cards and backgrounds are rendered procedurally (colored `Sprite` entities + text) — no image files are used and no `AssetServer` is needed.
-- Atomic file writes only: write to `filename.json.tmp`, then `rename()`.
-- Passwords and tokens are stored in the OS keychain via the `keyring` crate — never in plaintext files or logs.
-- Sync runs on `AsyncComputeTaskPool` — never block the Bevy main thread.
-- All sync backends implement the `SyncProvider` trait. The `SyncPlugin` is backend-agnostic — never `match` on `SyncBackend` inside a Bevy system.
-- `cargo clippy --workspace -- -D warnings` must pass clean after every change.
-- `cargo test --workspace` must pass after every change.
+## Commit format
+
+```text id="commit_fmt"
+type(scope): description
+```
+
+Examples:
+
+* feat(core): add draw-three rules
+* fix(engine): correct drag z-order
+* test(core): undo boundary cases
 
 ---
 
-## Code Style
+## Commit conditions
 
-- Use `thiserror` for error types. Never `Box<dyn Error>` in library crates.
-- Prefer `Into<T>` over concrete types in public API function parameters.
-- All public items must have doc comments (`///`). Private items: comment only when non-obvious.
-- Derive order convention: `#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]`
-- Bevy systems: one responsibility per system. Use `Events` for cross-system communication, never shared mutable state.
-- SQL queries: use `sqlx::query!` macros (compile-time checked), not raw string queries.
-- No `clone()` calls in hot paths (game loop systems). Profile before optimising elsewhere.
+* tests must pass
+* clippy must be clean
+
+NEVER commit otherwise
 
 ---
 
-## Bevy Conventions
+# 8. Change Control (ASK BEFORE DOING)
 
-- One `Plugin` per major feature: `CardPlugin`, `AudioPlugin`, `AchievementPlugin`, `UIPlugin`, `SyncPlugin`.
-- Resources own shared state. Events communicate between systems. Components own per-entity data.
-- All UI screens are built with Bevy UI (`bevy::ui`). Never mix UI layout and game logic in the same system.
-- Layout is recomputed on `WindowResized` — never assume a fixed window size.
+Claude must request confirmation before:
+
+* adding dependencies
+* modifying `solitaire_sync`
+* changing DB schema
+* introducing `unsafe`
+* changing merge strategy
 
 ---
 
-## Git Workflow
+# 9. System Mental Model (IMPORTANT)
 
-- Commit after each passing phase, not after every file change.
-- Commit message format: `type(scope): description`
-  - `feat(core): add draw-three mode validation`
-  - `fix(engine): card z-order during drag`
-  - `test(core): undo stack boundary conditions`
-  - `chore(server): add sqlx migration 002`
-- Never commit with failing tests or clippy warnings.
-- Never commit secrets, `.env` files, or `*.db` files.
+```text id="mental_model"
+Core (rules + deterministic logic)
+    ↓
+Engine (Bevy orchestration)
+    ↓
+Data layer (persistence + sync)
+    ↓
+Server (optional external system)
+```
+
+Core is always the source of truth.
 
 ---
 
-## Ask Before Doing
+# 10. Known Platform Pitfalls
 
-- Adding a new crate dependency (discuss alternatives first).
-- Changing a type in `solitaire_sync` (breaking change on both client and server).
-- Altering the database schema (requires a new sqlx migration).
-- Introducing `unsafe` code anywhere.
-- Changing the merge strategy in `solitaire_sync::merge()`.
+Must always be handled explicitly:
+
+* Bevy `Time` uses `f32`
+* `sqlx::migrate!()` path is crate-relative
+* `dirs::data_dir()` may return `None`
+* Linux may lack keyring backend
 
 ---
 
-## Lessons Learned
+# 11. Forbidden Patterns
 
-> Add entries here when Claude makes a mistake so it isn't repeated.
+* game logic inside Bevy systems
+* duplication across crates
+* blocking async calls in ECS
+* insecure credential storage
+* bypassing core logic layer
 
-- Bevy's `Time` resource uses `f32` seconds; convert to `u64` only when writing to `StatsSnapshot`.
-- `sqlx::migrate!()` macro path is relative to the crate root, not the workspace root.
-- `keyring` on Linux requires a running secret service (e.g. GNOME Keyring or KWallet) — handle `Error::NoStorageAccess` gracefully and fall back to prompting the user.
-- `dirs::data_dir()` returns `None` on some minimal Linux environments — always handle the `None` case explicitly, do not unwrap.
+---
+
+# 12. Execution Rules for Claude
+
+When generating code:
+
+1. respect crate boundaries
+2. minimize diff size
+3. do not expand scope
+4. follow existing patterns
+5. preserve invariants
+
+If unclear:
+→ ask before acting
+
+---
+
+# 13. Relationship to ARCHITECTURE.md
+
+| File            | Role                      |
+| --------------- | ------------------------- |
+| CLAUDE.md       | execution + constraints   |
+| ARCHITECTURE.md | system design truth       |
+| Both combined   | full system understanding |
+
+---
+# 14. Context Injection System (AUTOMATIC SCOPE FILTER)
+
+## 14.1 Purpose
+
+Before generating any response, Claude MUST construct a **minimal relevant context set**.
+
+This prevents:
+
+* architectural drift
+* irrelevant spec loading
+* over-engineering
+* cross-crate confusion
+
+---
+
+## 14.2 Input Classification Step (MANDATORY)
+
+Every request MUST be classified into exactly one task type:
+
+```text id="task_types"
+feature
+bugfix
+refactor
+system_design
+bevy_system
+core_logic
+sync
+optimization
+test
+debug
+```
+
+If uncertain → ask clarification.
+
+---
+
+## 14.3 Context Selection Engine
+
+After classification, Claude MUST include ONLY the relevant sections below.
+
+---
+
+## 14.4 Context Map (CORE RULESET)
+
+### feature
+
+Include:
+
+* §2 Hard Global Constraints
+* §3 Engine Rules
+* ARCHITECTURE.md (crate of target feature only)
+* relevant data models (GameState, SyncPayload if needed)
+
+---
+
+### bugfix
+
+Include:
+
+* §2 Hard Global Constraints
+* §5 Code Standards
+* affected crate boundaries
+* relevant system (engine/core/sync only)
+
+---
+
+### refactor
+
+Include:
+
+* §3 Engine Rules
+* §5 Code Standards
+* §11 Forbidden Patterns
+* target crate boundaries
+
+---
+
+### system_design
+
+Include:
+
+* ARCHITECTURE.md (FULL)
+* §9 Mental Model
+* §1 System Architecture Mapping
+
+---
+
+### core_logic
+
+Include:
+
+* solitaire_core rules only
+* GameState model
+* MoveError model
+* §2.1–2.3 constraints
+
+---
+
+### bevy_system
+
+Include:
+
+* §3 Engine Rules
+* ECS rules (Events/Resources/Components)
+* UI-first constraint
+* relevant plugin system only
+
+---
+
+### sync
+
+Include:
+
+* SyncProvider trait
+* merge strategy rules
+* solitaire_sync models
+* §2.6 Sync Rules
+
+---
+
+### optimization
+
+Include:
+
+* target crate only
+* §5.4 Performance Rules
+* hot path constraints
+
+---
+
+### test
+
+Include:
+
+* §6 Build Rules
+* relevant module
+* expected invariants
+
+---
+
+### debug
+
+Include:
+
+* target file/module only
+* §2.3 Error Policy
+* runtime assumptions relevant to failure
+
+---
+
+## 14.5 Context Compression Rules
+
+Claude MUST obey:
+
+* never include full ARCHITECTURE.md unless system_design
+* max 2 crates per response unless explicitly required
+* prefer function-level context over file-level context
+* exclude unrelated plugins/systems
+
+---
+
+## 14.6 Context Priority Order
+
+When space is limited:
+
+1. Hard Constraints (§2)
+2. Target crate rules
+3. Data models
+4. Only then: architecture snippets
+
+---
+
+## 14.7 “No Context Pollution” Rule
+
+Claude must NOT include:
+
+* unrelated crates
+* unrelated plugins
+* unused data models
+* full architecture dumps
+* speculative systems
+
+---
+
+## 14.8 Self-Check Before Execution
+
+Before writing code, Claude MUST verify:
+
+* [ ] Is only relevant context included?
+* [ ] Is at least one hard constraint present?
+* [ ] Am I touching more than one crate unnecessarily?
+* [ ] Am I duplicating ARCHITECTURE.md content?
+
+If any fail → revise context selection.
+
+---
+
+## 14.9 Injection Output Format (Internal Model)
+
+Claude should behave as if it constructed:
+
+```text id="ctx_format"
+[SELECTED TASK TYPE]
+
+[MINIMAL REQUIRED RULES]
+
+[MINIMAL ARCHITECTURE SLICES]
+
+[RELEVANT MODELS]
+
+[REQUEST]
+```
+
+---
+
+## 14.10 Relationship to ARCHITECTURE.md
+
+* ARCHITECTURE.md = source of truth
+* CLAUDE.md = execution constraints
+* THIS SECTION = filtering layer between them
+
+---
+
+# END CONTEXT INJECTION SYSTEM

CLAUDE_PROMPT_PACK.md

@@ -0,0 +1,497 @@
+# CLAUDE_PROMPT_PACK.md
+
+version: 1.0
+
+---
+
+# 0. GLOBAL INSTRUCTION (prepend to every prompt)
+
+```
+You must follow CLAUDE_SPEC.md strictly.
+
+Rules:
+- Do not expand scope beyond what is defined
+- Do not refactor unrelated code
+- Do not introduce new dependencies
+- Prefer minimal, surgical changes
+- Use existing patterns in the codebase
+- Return minimal diffs or changed functions only
+
+Before writing code:
+1. List relevant constraints from CLAUDE_SPEC.md
+2. Identify risks
+3. Then implement
+```
+
+---
+
+# 1. FEATURE IMPLEMENTATION
+
+```
+# TASK: Feature Implementation
+
+feature: "<name>"
+
+goal:
+"<clear outcome>"
+
+scope:
+crates: []
+systems: []
+files: []
+
+non_goals:
+- ""
+
+constraints:
+- must follow CLAUDE_SPEC.md
+- event-driven architecture required
+- no blocking operations
+- no cross-crate leakage
+
+acceptance_criteria:
+- ""
+- ""
+
+edge_cases:
+- ""
+
+---
+
+## Required Patterns
+
+Use this pattern for systems:
+<PASTE EXISTING SYSTEM SNIPPET HERE>
+
+---
+
+## Output Format
+
+intent:
+plan:
+constraints_used:
+risks:
+
+code_changes:
+(minimal diffs only)
+
+notes:
+```
+
+---
+
+# 2. BUGFIX
+
+```
+# TASK: Bug Fix
+
+bug_description:
+"<what is broken>"
+
+expected_behavior:
+"<correct behavior>"
+
+root_cause_hint (optional):
+""
+
+scope:
+crates: []
+files: []
+
+constraints:
+- minimal fix only
+- no refactors unless required
+- must add regression protection if applicable
+
+---
+
+## Requirements
+
+1. Identify root cause
+2. Fix it minimally
+3. Preserve all invariants
+4. Do not change unrelated logic
+
+---
+
+## Output Format
+
+analysis:
+root_cause:
+fix_strategy:
+
+code_changes:
+(minimal diff)
+
+regression_test (only if high-value):
+
+notes:
+```
+
+---
+
+# 3. REFACTOR
+
+```
+# TASK: Refactor
+
+target:
+"<what is being improved>"
+
+goal:
+"<what improves>"
+
+scope:
+crates: []
+files: []
+
+non_goals:
+- no behavior changes
+- no new features
+
+constraints:
+- must preserve behavior exactly
+- must respect crate boundaries
+- must not duplicate logic
+
+---
+
+## Refactor Type
+
+- [ ] simplify logic
+- [ ] reduce duplication
+- [ ] improve readability
+- [ ] performance (non-invasive)
+
+---
+
+## Output Format
+
+analysis:
+issues_found:
+
+refactor_plan:
+
+code_changes:
+(diff only)
+
+verification:
+- behavior unchanged: yes/no
+- invariants preserved: yes/no
+
+notes:
+```
+
+---
+
+# 4. SYSTEM DESIGN (NEW FEATURE)
+
+```
+# TASK: System Design
+
+feature:
+"<name>"
+
+goal:
+"<what problem it solves>"
+
+constraints:
+- must fit existing architecture
+- must follow plugin + event model
+- must not violate crate boundaries
+
+---
+
+## Required Output
+
+design:
+
+components:
+- plugins:
+- systems:
+- events:
+- resources:
+
+data_flow:
+(step-by-step)
+
+integration_points:
+- where it connects to existing systems
+
+risks:
+- ""
+
+tradeoffs:
+- ""
+
+---
+
+## DO NOT
+
+- write full implementation
+- modify unrelated systems
+```
+
+---
+
+# 5. NEW BEVY SYSTEM
+
+```
+# TASK: Add Bevy System
+
+system_name:
+""
+
+trigger:
+(event or condition)
+
+reads:
+[Resources]
+
+writes:
+[Resources]
+
+emits:
+[Events]
+
+constraints:
+- must be event-driven
+- must not directly mutate unrelated state
+- must be single responsibility
+
+---
+
+## Output Format
+
+system_signature:
+
+implementation:
+(code only)
+
+notes:
+```
+
+---
+
+# 6. CORE LOGIC FUNCTION (solitaire_core)
+
+```
+# TASK: Core Logic Implementation
+
+function:
+"<name>"
+
+goal:
+"<what it does>"
+
+rules:
+- no IO
+- no async
+- no Bevy
+- deterministic
+
+invariants:
+- ""
+- ""
+
+errors:
+- ""
+
+---
+
+## Output Format
+
+constraints_checked:
+
+implementation:
+(code only)
+
+edge_case_handling:
+
+notes:
+```
+
+---
+
+# 7. SYNC / MERGE LOGIC
+
+```
+# TASK: Sync Logic
+
+goal:
+"<what is being merged or synced>"
+
+constraints:
+- must be deterministic
+- must be idempotent
+- must be lossless
+- must not delete data
+
+rules:
+- counters → max
+- times → min
+- collections → union
+
+---
+
+## Output Format
+
+analysis:
+
+merge_logic:
+
+code_changes:
+
+invariants_verified:
+- deterministic
+- idempotent
+- lossless
+
+notes:
+```
+
+---
+
+# 8. PERFORMANCE OPTIMIZATION
+
+```
+# TASK: Optimization
+
+target:
+"<what is slow>"
+
+constraints:CLAUDE_WORKFLOW.md
+- no behavior change
+- no architecture change
+- minimal code changes
+
+---
+
+## Output Format
+
+analysis:
+bottleneck:
+
+optimization_strategy:
+
+code_changes:
+
+impact_estimate:
+
+notes:
+```
+
+---
+
+# 9. TEST GENERATION (STRICT MODE)
+
+```
+# TASK: Test Generation
+
+target:
+"<function/system>"
+
+reason:
+- bugfix | complex logic | invariant protection
+
+constraints:
+- no redundant tests
+- must test real behavior
+- must fail if logic breaks
+
+---
+
+## Output Format
+
+test_cases:
+- ""
+
+test_code:
+
+notes:
+```
+
+---
+
+# 10. DEBUGGING / INVESTIGATION
+
+```
+# TASK: Debug
+
+problem:
+"<symptom>"
+
+context:
+"<relevant code or system>"
+
+---
+
+## Required Steps
+
+1. List possible causes
+2. Narrow down most likely
+3. Suggest verification steps
+4. Provide minimal fix
+
+---
+
+## Output Format
+
+hypotheses:
+
+most_likely:
+
+verification_steps:
+
+fix:
+
+notes:
+```
+
+---
+
+# 11. HARD CONSTRAINT OVERRIDE (RARE)
+
+```
+# TASK: Exception Handling
+
+reason:
+"<why constraints must be bent>"
+
+requested_exception:
+"<rule being broken>"
+
+justification:
+"<why unavoidable>"
+
+---
+
+## Output Format
+
+analysis:
+
+alternatives_considered:
+
+final_decision:
+
+risk:
+```
+
+---
+
+# 12. STOP CONDITIONS (always append)
+
+```
+Stop when:
+- acceptance criteria are met
+- code is minimal and correct
+
+Do NOT:
+- expand scope
+- refactor unrelated code
+- optimize prematurely
+```
+
+---
+
+# END

CLAUDE_SPEC.md

@@ -0,0 +1,292 @@
+# CLAUDE_SPEC.md
+
+version: 1.0
+
+---
+
+## 0. Global Rules
+
+(Core determinism, panic policy, and event-driven engine constraints live in CLAUDE.md §2.1, §2.3, §3.1. Listed here only when they add information CLAUDE.md doesn't carry.)
+
+rules:
+
+* id: single_source_of_truth
+  description: "GameStateResource is the only mutable game state in runtime"
+
+* id: sync_is_additive
+  description: "Remote data must never destructively overwrite local data"
+
+---
+
+## 1. Crate Graph
+
+crates:
+solitaire_core:
+depends_on: [rand, serde, chrono]
+forbidden_deps: [bevy, reqwest, tokio, std::fs]
+
+solitaire_sync:
+depends_on: [serde, serde_json, uuid, chrono]
+role: "shared_types"
+
+solitaire_data:
+depends_on: [solitaire_core, solitaire_sync, reqwest, tokio, keyring]
+role: "persistence_and_sync"
+
+solitaire_engine:
+depends_on: [bevy, kira, solitaire_core, solitaire_data]
+role: "runtime_engine"
+
+solitaire_server:
+depends_on: [solitaire_sync, axum, sqlx, jsonwebtoken]
+role: "backend"
+
+solitaire_app:
+depends_on: [solitaire_engine]
+role: "entrypoint"
+
+---
+
+## 2. Data Ownership
+
+ownership:
+GameState:
+owner: solitaire_core
+mutable_in: solitaire_engine
+access_pattern: "via GameStateResource only"
+
+StatsSnapshot:
+owner: solitaire_data
+
+PlayerProgress:
+owner: solitaire_data
+
+AchievementRecord:
+owner: solitaire_data
+
+SyncPayload:
+owner: solitaire_sync
+
+---
+
+## 3. State Transitions
+
+state_machine:
+GameState:
+transitions:
+- action: move_cards
+returns: Result<GameState, MoveError>
+
+```
+  - action: draw
+    returns: Result<GameState, MoveError>
+
+  - action: undo
+    returns: Result<GameState, MoveError>
+
+invariants:
+  - "52 cards always exist"
+  - "no duplicate card IDs"
+  - "all cards belong to exactly one pile"
+```
+
+---
+
+## 4. Event System
+
+events:
+
+input:
+- MoveRequestEvent
+- DrawRequestEvent
+- UndoRequestEvent
+- NewGameRequestEvent
+
+state:
+- StateChangedEvent
+- GameWonEvent
+
+meta:
+- AchievementUnlockedEvent
+- SyncCompleteEvent
+
+rules:
+
+* "Input events trigger core logic"
+* "Core logic emits state events"
+* "UI reacts to state events only"
+
+---
+
+## 5. Sync Contract
+
+sync:
+
+provider_trait:
+methods:
+- pull() -> SyncPayload
+- push(payload) -> SyncResponse
+
+guarantees:
+- "non-blocking during gameplay"
+- "blocking allowed on exit only"
+
+merge:
+rules:
+counters: "max"
+best_times: "min"
+collections: "union"
+achievements: "never removed"
+
+```
+properties:
+  - deterministic
+  - idempotent
+  - lossless
+```
+
+---
+
+## 6. Persistence
+
+storage:
+
+format: json
+
+files:
+- stats.json
+- progress.json
+- achievements.json
+- settings.json
+- game_state.json
+
+guarantees:
+- atomic_write: true
+- crash_safe: true
+
+---
+
+## 7. Engine Rules
+
+engine:
+
+mutation_rules:
+- "Only GameLogicSystem mutates GameState"
+- "UI systems are read-only"
+
+threading:
+- "sync runs on AsyncComputeTaskPool"
+- "main thread must never block"
+
+plugins:
+pattern: "feature_isolation"
+communication: "events"
+
+---
+
+## 8. Server Contract
+
+server:
+
+auth:
+method: jwt
+access_expiry: 24h
+refresh_expiry: 30d
+
+endpoints:
+- POST /api/auth/register
+- POST /api/auth/login
+- GET /api/sync/pull
+- POST /api/sync/push
+
+limits:
+payload_max: 1MB
+rate_limit: "10 req/min auth routes"
+
+---
+
+## 9. Achievement System
+
+achievements:
+
+definition_location: solitaire_core
+state_location: solitaire_data
+
+types:
+- condition_based
+- event_driven
+
+rule:
+- "achievements cannot be revoked"
+
+---
+
+## 10. Testing Rules
+
+testing:
+
+philosophy:
+- "test real failures"
+- "avoid redundant tests"
+
+required_coverage:
+solitaire_core:
+- move_validation
+- undo_integrity
+- win_detection
+
+```
+solitaire_sync:
+  - merge_correctness
+  - idempotency
+```
+
+---
+
+## 11. Prohibited Patterns
+
+(See CLAUDE.md §11 for the canonical forbidden-patterns list.)
+
+---
+
+## 12. Extension Points
+
+extensibility:
+
+sync_backends:
+pattern: "implement SyncProvider"
+
+game_modes:
+location: solitaire_core::GameMode
+
+plugins:
+rule: "new feature = new plugin"
+
+---
+
+## 13. Validation Checklist (for Claude)
+
+validation:
+
+* check: "crate dependency rules respected"
+* check: "no panics in core"
+* check: "events used for cross-system communication"
+* check: "GameState mutations centralized"
+* check: "merge function properties preserved"
+* check: "no blocking operations in main loop"
+
+---
+
+## 14. Mental Model
+
+model:
+
+layers:
+- core
+- engine
+- data
+- server
+
+flow:
+- input -> engine -> core -> engine -> ui
+- data <-> sync <-> server

CLAUDE_WORKFLOW.md

@@ -0,0 +1,335 @@
+# CLAUDE_WORKFLOW.md
+
+version: 1.0
+
+---
+
+## 0. Overview
+
+This workflow defines a **two-agent system**:
+
+* **Builder Agent** → writes and modifies code
+* **Guardian Agent** → enforces architecture + rejects invalid changes
+
+No code is considered valid unless it passes Guardian validation.
+
+---
+
+## 1. Agent Roles
+
+### 1.1 Builder Agent
+
+role: "code_generation"
+
+responsibilities:
+
+* implement features
+* refactor code
+* generate tests (only when justified)
+* follow CLAUDE_SPEC.md
+
+constraints:
+
+* cannot bypass validation
+* must declare intent before writing code
+
+output_contract:
+must_produce:
+- change_summary
+- files_modified
+- reasoning (short)
+- code_diff
+
+---
+
+### 1.2 Guardian Agent
+
+role: "architecture_enforcement"
+
+responsibilities:
+
+* validate against CLAUDE_SPEC.md
+* detect violations
+* reject or approve changes
+* suggest minimal fixes (not full rewrites)
+
+constraints:
+
+* no feature implementation
+* no large rewrites
+* must be deterministic
+
+output_contract:
+must_produce:
+- status: APPROVED | REJECTED
+- violations[]
+- required_fixes[]
+- optional_improvements[]
+
+---
+
+## 2. Workflow Pipeline
+
+```text
+User Request
+    ↓
+Builder Agent (proposal + code)
+    ↓
+Guardian Agent (validation)
+    ↓
+IF approved → commit
+IF rejected → feedback → Builder retry
+```
+
+---
+
+## 3. Builder Protocol
+
+### Step 1 — Intent Declaration
+
+Builder MUST start with:
+
+```yaml
+intent:
+  feature: "<name>"
+  crates_touched: []
+  systems_affected: []
+  risk_level: low|medium|high
+```
+
+---
+
+### Step 2 — Plan
+
+```yaml
+plan:
+  - step: "..."
+  - step: "..."
+```
+
+---
+
+### Step 3 — Implementation
+
+* Only modify declared crates
+* Follow ownership rules
+* Use events for cross-system communication
+
+---
+
+### Step 4 — Output
+
+```yaml
+change_summary: "..."
+
+files_modified:
+  - path: ...
+    change: "..."
+
+violations_self_check:
+  - none | list
+
+notes: "short reasoning"
+```
+
+---
+
+## 4. Guardian Protocol
+
+### Step 1 — Spec Validation
+
+Check against:
+
+* crate boundaries
+* mutation rules
+* event system usage
+* sync guarantees
+* forbidden patterns
+
+---
+
+### Step 2 — Invariant Validation
+
+Must verify:
+
+* GameState invariants preserved
+* no new panic paths
+* no blocking calls in engine
+* merge properties unchanged
+
+---
+
+### Step 3 — Output Decision
+
+#### APPROVED
+
+```yaml
+status: APPROVED
+
+notes:
+  - "no violations"
+```
+
+---
+
+#### REJECTED
+
+```yaml
+status: REJECTED
+
+violations:
+  - id: core_purity_violation
+    file: "solitaire_core/src/..."
+    reason: "uses std::fs"
+
+required_fixes:
+  - "move IO to solitaire_data"
+
+optional_improvements:
+  - "simplify event naming"
+```
+
+---
+
+## 5. Enforcement Rules
+
+### Hard Fail (automatic rejection)
+
+* core crate uses IO / Bevy / network
+* GameState mutated outside GameLogicSystem
+* blocking async on main thread
+* duplicate logic across crates
+* merge function altered incorrectly
+
+---
+
+### Soft Fail (allowed but flagged)
+
+* unnecessary complexity
+* redundant tests
+* minor architectural drift
+
+---
+
+## 6. Iteration Loop
+
+Max attempts per task: **3**
+
+```text
+Attempt 1 → Reject → Fix
+Attempt 2 → Reject → Fix
+Attempt 3 → Final decision
+```
+
+If still failing:
+→ escalate to user
+
+---
+
+## 7. Diff Strategy
+
+Builder MUST produce:
+
+* minimal diffs
+* no unrelated refactors
+* no formatting-only changes
+
+---
+
+## 8. Test Strategy Integration
+
+Builder rules:
+
+* only add tests if:
+
+  * fixing a bug
+  * protecting complex logic
+  * validating invariants
+
+Guardian rejects:
+
+* redundant tests
+* no-op tests
+
+---
+
+## 9. Optional Extensions
+
+### 9.1 Third Agent (Optimizer)
+
+role: performance + cleanup
+
+runs AFTER approval:
+
+* reduce allocations
+* simplify logic
+* improve ECS scheduling
+
+---
+
+### 9.2 CI Integration
+
+Pipeline:
+
+```text
+Builder → Guardian → cargo check → clippy → tests
+```
+
+Guardian runs BEFORE compilation to catch structural issues early.
+
+---
+
+## 10. Example Interaction
+
+### Builder
+
+```yaml
+intent:
+  feature: "undo stack limit fix"
+  crates_touched: [solitaire_core]
+  risk_level: low
+```
+
+```yaml
+change_summary: "limit undo stack to 64 entries"
+
+files_modified:
+  - solitaire_core/src/game_state.rs
+
+notes: "prevents unbounded memory growth"
+```
+
+---
+
+### Guardian
+
+```yaml
+status: APPROVED
+
+notes:
+  - "respects core constraints"
+  - "no invariant violations"
+```
+
+---
+
+## 11. Mental Model
+
+* Builder = **creative**
+* Guardian = **strict**
+
+Builder explores
+Guardian enforces
+
+Neither replaces the other.
+
+---
+
+## 12. Success Criteria
+
+System is working if:
+
+* architectural violations go to ~0
+* code stays consistent across features
+* refactors become safe
+* complexity grows sub-linearly

CREDITS.md

@@ -0,0 +1,112 @@
+# Credits
+
+Solitaire Quest is MIT-licensed (see [LICENSE](LICENSE)). It is built on top of
+the work of many open-source projects and a small handful of third-party
+assets. This file lists every component that ships in the binary or in the
+`assets/` directory.
+
+---
+
+## Code & Framework
+
+| Component | License | Role |
+|---|---|---|
+| [Bevy 0.18](https://bevyengine.org/) | MIT OR Apache-2.0 | Game engine, ECS, rendering, UI |
+| [kira 0.12](https://crates.io/crates/kira) | MIT OR Apache-2.0 | Audio playback (mixer, sub-tracks, looping ambient) |
+| [serde](https://crates.io/crates/serde) / [serde_json](https://crates.io/crates/serde_json) | MIT OR Apache-2.0 | Serialization for save files and the sync API |
+| [tokio](https://crates.io/crates/tokio) | MIT | Async runtime for the sync client and server |
+| [axum 0.8](https://crates.io/crates/axum) | MIT | HTTP framework for the self-hosted sync server |
+| [sqlx 0.8](https://crates.io/crates/sqlx) | MIT OR Apache-2.0 | Compile-time-checked SQLite access on the server |
+| [reqwest 0.13](https://crates.io/crates/reqwest) | MIT OR Apache-2.0 | HTTP client for the sync provider |
+| [jsonwebtoken 10](https://crates.io/crates/jsonwebtoken) | MIT | JWT issuance and validation |
+| [bcrypt 0.19](https://crates.io/crates/bcrypt) | MIT | Password hashing on the server |
+| [keyring 4](https://crates.io/crates/keyring) | MIT OR Apache-2.0 | OS keychain integration for credential storage |
+| [tower-governor 0.8](https://crates.io/crates/tower-governor) | MIT | Rate limiting on `/api/auth/*` |
+| [chrono](https://crates.io/crates/chrono) | MIT OR Apache-2.0 | Date / time handling |
+| [uuid](https://crates.io/crates/uuid) | MIT OR Apache-2.0 | User and session identifiers |
+| [thiserror](https://crates.io/crates/thiserror) | MIT OR Apache-2.0 | Error type derive |
+| [rand 0.9](https://crates.io/crates/rand) | MIT OR Apache-2.0 | Seeded shuffler in `solitaire_core` |
+| [png 0.17](https://crates.io/crates/png) | MIT OR Apache-2.0 | PNG encoder used by `solitaire_assetgen` |
+| [ab_glyph 0.2](https://crates.io/crates/ab_glyph) | Apache-2.0 | Glyph rasterization for generated card art |
+
+The full transitive dependency tree (several hundred crates) is captured in
+`Cargo.lock` and reachable via `cargo tree`. Every crate brought in is
+MIT, Apache-2.0, BSD-style, or a dual-licensed combination thereof — no
+copyleft code is statically linked into the game binary.
+
+---
+
+## Assets
+
+### Card artwork
+
+| File(s) | Source | License |
+|---|---|---|
+| `solitaire_engine/assets/themes/default/{suit}_{rank}.svg` (52 SVGs) | [hayeah/playing-cards-assets](https://github.com/hayeah/playing-cards-assets) | MIT |
+| `solitaire_engine/assets/themes/default/back.svg` | Original — Solitaire Quest | MIT (this project) |
+| `assets/cards/faces/{RANK}{SUIT}.png` (52 PNGs) | Pre-rendered from the same `playing-cards-assets` SVGs | MIT (passed through from hayeah) |
+| `assets/cards/backs/back_0.png` – `back_4.png` | Original — generated by `solitaire_assetgen::gen_art` | MIT (this project) |
+
+The face SVGs come from Howard Yeh's `playing-cards-assets` repository, which
+is itself derived from the public-domain `vector-playing-cards` Google Code
+project. The art is redistributed under the MIT license — see the upstream
+repository for the full notice. The files ship unmodified in the bundled
+default theme; user-supplied themes can override them per-installation
+through the runtime SVG theming system documented in `CARD_PLAN.md`.
+
+The default card back is original work by this project, midnight-purple
+themed to match the rest of the UI palette.
+
+### Backgrounds
+
+| File(s) | Source | License |
+|---|---|---|
+| `assets/backgrounds/bg_0.png` – `bg_4.png` | Original — generated by `solitaire_assetgen::gen_art` | MIT (this project) |
+
+### Typography
+
+| File | Source | License |
+|---|---|---|
+| `assets/fonts/main.ttf` (FiraMono-Medium) | [mozilla/Fira](https://github.com/mozilla/Fira) | SIL Open Font License 1.1 |
+
+The OFL permits redistribution and embedding in software so long as the font
+file itself is not sold standalone. The file ships unmodified.
+
+### Audio
+
+All six WAV files in `assets/audio/` are **original work** — there are no
+third-party audio samples in this project. They are synthesized
+programmatically by `solitaire_assetgen/src/bin/gen_sfx.rs`, which writes
+44.1 kHz mono 16-bit PCM WAVs using a hand-rolled WAV writer (no `hound` or
+`dasp` dependency). The synthesis stack is entirely additive: sine /
+square waves, layered harmonics, deterministic LCG noise, AR envelopes,
+and a slow LFO for the ambient track.
+
+| File | Synthesis approach |
+|---|---|
+| `card_deal.wav` | Filtered LCG noise with a sweeping low-pass cutoff for a "whoosh" |
+| `card_flip.wav` | High-passed LCG noise under a fast AR envelope |
+| `card_place.wav` | 120 Hz sine body + filtered noise click |
+| `card_invalid.wav` | Two dissonant square tones (196 Hz + 207.65 Hz) beating against each other |
+| `win_fanfare.wav` | C-major arpeggio (C5 / E5 / G5 / C6) with sine + 2nd harmonic |
+| `ambient_loop.wav` | 55 Hz fundamental with 2nd and 3rd harmonics, modulated by a 0.2 Hz LFO; loop length is chosen so the tone and LFO both complete an integer number of cycles for seamless looping |
+
+Audio files are MIT-licensed alongside the rest of this project.
+
+---
+
+## License Summary
+
+- **Project code:** MIT — see [LICENSE](LICENSE).
+- **Card face artwork (52 SVGs from hayeah/playing-cards-assets, plus the
+  pre-rendered PNGs in `assets/cards/faces/`):** MIT, redistributed
+  unmodified. The original `vector-playing-cards` line art is itself
+  public domain.
+- **FiraMono-Medium font:** SIL Open Font License 1.1, redistributed unmodified.
+- **All other assets** (backgrounds, the default `back.svg`, generated card
+  backs, every audio file) are original work covered by this project's MIT
+  license.
+
+If you redistribute Solitaire Quest, you must ship this `CREDITS.md` and the
+`LICENSE` file alongside the binary so the MIT (project + hayeah card art)
+and OFL (FiraMono) notices remain visible to end users.

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     "solitaire_server",
     "solitaire_app",
     "solitaire_assetgen",
+    "solitaire_wasm",
 ]
 resolver = "2"
 
@@ -29,15 +30,79 @@ dirs        = "6"
 keyring     = "4"
 keyring-core = "1"
 reqwest     = { version = "0.13", features = ["json", "rustls", "rustls-native-certs"], default-features = false }
+arboard     = { version = "3", default-features = false }
 
 solitaire_core   = { path = "solitaire_core" }
 solitaire_sync   = { path = "solitaire_sync" }
 solitaire_data   = { path = "solitaire_data" }
 solitaire_engine = { path = "solitaire_engine" }
 
-bevy = "0.18"
+# Bevy with `default-features = false` to avoid the unused
+# `bevy_audio → rodio + symphonia + cpal 0.15 + alsa 0.9` chain.
+# Audio is handled directly by `kira` in `audio_plugin.rs`, so the
+# `bevy_audio` feature is intentionally omitted. The features below
+# enumerate every leaf of the standard `2d` + `ui` meta-features that
+# we actually use; new features should only be added with a
+# corresponding use site.
+bevy = { version = "0.18", default-features = false, features = [
+    # default_app
+    "async_executor",
+    "bevy_asset",
+    "bevy_input_focus",
+    "bevy_log",
+    "bevy_state",
+    "bevy_window",
+    "custom_cursor",
+    "reflect_auto_register",
+    # default_platform (desktop subset; no android/wayland/webgl/gilrs/sysinfo)
+    "std",
+    "bevy_winit",
+    "default_font",
+    "multi_threaded",
+    "x11",
+    # common_api
+    "bevy_color",
+    "bevy_image",
+    "bevy_mesh",
+    "bevy_shader",
+    "bevy_text",
+    "png",
+    # 2d rendering
+    "bevy_camera",
+    "bevy_render",
+    "bevy_core_pipeline",
+    "bevy_sprite",
+    "bevy_sprite_render",
+    # UI rendering
+    "bevy_ui",
+    "bevy_ui_render",
+] }
 kira = "0.12"
 
+# SVG rasterisation pipeline for the runtime card-theme system.
+# usvg parses + simplifies; resvg renders to a tiny-skia Pixmap;
+# tiny-skia provides the CPU rasteriser. All three are maintained
+# together by the resvg-rs project and version in lockstep.
+usvg      = "0.47"
+resvg     = "0.47"
+tiny-skia = "0.12"
+
+# Theme manifest format. RON keeps the file human-editable while
+# preserving Rust-style structures the importer can validate.
+ron = "0.12"
+
+# Importer-only: reads user-supplied theme zip archives, validates
+# their contents, and unpacks them into the user themes directory.
+# Default features are disabled to keep the dependency footprint small;
+# only `deflate` is needed because the importer rejects other
+# compression methods anyway (see Phase 7 spec).
+zip = { version = "8.6", default-features = false, features = ["deflate"] }
+
+# Importer-only test dependency: tests build zip archives in a
+# scratch directory so they don't pollute the real user themes path
+# on the developer's machine.
+tempfile = "3.27"
+
 axum               = "0.8"
 sqlx               = { version = "0.8", features = ["runtime-tokio-rustls", "sqlite", "macros", "migrate"] }
 jsonwebtoken       = { version = "10", default-features = false, features = ["rust_crypto"] }

README.md

@@ -1,17 +1,35 @@
 # Solitaire Quest
 
-A cross-platform Klondike Solitaire game written in Rust, featuring a full progression system with XP, levels, achievements, daily challenges, and optional self-hosted sync so your stats follow you across machines.
+A cross-platform Klondike Solitaire game written in Rust, with a card-theme
+system, full progression (XP / levels / achievements / daily challenges), and
+optional self-hosted sync so your stats follow you across machines.
 
 ## Features
 
-- **Klondike Solitaire** — Draw One and Draw Three modes
+- **Klondike Solitaire** — Draw One and Draw Three modes; foundations are
+  unlocked (any Ace lands in any empty slot, the slot then claims that suit)
+- **Card themes** — bundled hayeah/playing-cards-assets default plus
+  user-installable themes (drop a directory under the data dir or import a
+  zip from Settings → Cosmetic)
+- **Modern HUD** — reserved top band keeps cards from crowding the score
+  readout; the action bar auto-fades when the cursor leaves it so it can't
+  compete with the play surface
+- **Drag feel** — every legal drop target is highlighted in green during
+  drag; cards cast a soft drop shadow that lifts when picked up; the stock
+  pile shows a remaining-count chip so you can see how close you are to a
+  recycle
+- **Keyboard navigation** — Tab cycles focus through buttons, arrow keys
+  move within picker rows, Enter activates; works across every modal and
+  the HUD action bar
 - **Progression** — XP, levels, unlockable card backs and backgrounds
-- **18 Achievements** — including secret ones
-- **Daily Challenge** — server-seeded so every player worldwide gets the same deal
+- **19 Achievements** — including secret ones
+- **Daily Challenge** — server-seeded so every player worldwide gets the
+  same deal
 - **Leaderboard** — opt-in, powered by your own self-hosted server
 - **Special Modes** (unlocked at level 5): Zen, Time Attack, Challenge
 - **Sync** — pull/push stats across devices via a self-hosted server
-- **Color-blind mode** — blue tint on red-suit cards
+- **Color-blind mode** — blue tint on red-suit cards alongside the suit
+  glyph
 
 ## Building
 
@@ -32,42 +50,73 @@ cargo build -p solitaire_app --release
 
 ## Controls
 
+Every action also has a visible UI button — keyboard shortcuts are optional
+accelerators.
+
 | Key | Action |
 |---|---|
 | Left click / drag | Move cards |
+| Double click | Auto-move card to its best legal destination |
 | Right click | Highlight legal moves for a card |
 | Space / D | Draw from stock |
-| Z / Ctrl+Z | Undo |
+| U | Undo |
+| H | Hint (highlight a legal move) |
 | N | New game |
-| S | Stats overlay |
-| A | Achievements overlay |
-| P | Profile overlay |
-| O | Settings |
-| L | Leaderboard |
-| H | Help / controls |
-| Enter | Auto-complete (when badge is lit) |
-| Escape | Pause / clear selection |
-| Arrow keys | Navigate card selection |
+| Z | Zen mode |
+| G | Forfeit (during pause) |
+| Tab / Shift+Tab | Cycle keyboard focus |
+| Enter | Activate focused button / auto-complete (when badge is lit) |
+| Esc | Pause / dismiss modal |
+| F1 | Help / controls |
+| F11 | Toggle fullscreen |
+| S / A / P / O / L / M | Stats / Achievements / Profile / Settings / Leaderboard / Menu |
+
+## Card themes
+
+The default theme ships embedded in the binary, so the game runs
+self-contained with no external assets. To install another theme, drop a
+directory containing a `theme.ron` manifest plus 53 SVG files (52 faces +
+1 back) under the platform data dir's `themes/` folder, or import a zip
+from **Settings → Cosmetic**. The picker chip lights up the moment a new
+theme is registered. Themes are SVG-based, so they rasterise cleanly at
+whatever resolution the window happens to be.
 
 ## Sync Server (optional)
 
-To sync stats across machines, run the self-hosted server. See [README_SERVER.md](README_SERVER.md) for setup instructions.
+To sync stats across machines, run the self-hosted server. See
+[README_SERVER.md](README_SERVER.md) for setup instructions.
 
-Once the server is running, open **Settings → Sync Backend**, enter the server URL and your username, and register an account from within the game.
+Once the server is running, open **Settings → Sync Backend**, enter the
+server URL and your username, and register an account from within the
+game.
 
 ## Running Tests
 
 ```bash
-# All tests
+# All tests (982 passing as of v0.11.0)
 cargo test --workspace
 
 # Just game logic (no display required)
 cargo test -p solitaire_core -p solitaire_sync -p solitaire_data -p solitaire_server
 
 # Lint
-cargo clippy --workspace -- -D warnings
+cargo clippy --workspace --all-targets -- -D warnings
 ```
 
+## Credits
+
+Built on [Bevy](https://bevyengine.org/) and the wider Rust ecosystem
+(Tokio, Axum, sqlx, Serde, kira, and many more). Card faces come from
+[hayeah/playing-cards-assets](https://github.com/hayeah/playing-cards-assets)
+(MIT, derived from the public-domain `vector-playing-cards` library); the
+default card back is original work; the UI font is FiraMono-Medium (OFL).
+All audio is synthesized programmatically by this project. See
+[CREDITS.md](CREDITS.md) for the full list and license details.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

SESSION_HANDOFF.md

@@ -0,0 +1,179 @@
+# Solitaire Quest — Session Handoff
+
+**Last updated:** 2026-05-06 (post-v0.18.0 draft) — 24 commits since
+the v0.17.0 tag bundle the launch-experience round (Restore prompt +
+auto-show Home / mode picker), the MSSC-style Home picker rework
+(header chips, draw-mode chips, picture-tile mode cards, Today's
+Event callout, glyph fixes), the last solver hot path moving onto
+`AsyncComputeTaskPool`, "Won before" HUD chip, "Copy share link"
+Stats button, the `N` keybinding finally routing through the real
+Confirm/Cancel modal, Esc-on-modal layering fixes, and the
+unified-3.0 Claude rule set (CLAUDE.md / CLAUDE_SPEC.md /
+CLAUDE_WORKFLOW.md / CLAUDE_PROMPT_PACK.md). Test-discipline prune
+removed 43 low-value tests in the same window.
+
+## Status at pause
+
+- **HEAD on origin:** `v0.17.0-24-gc497c31` (24 ahead of v0.17.0,
+  not yet tagged).
+- **Working tree:** clean.
+- **Build:** `cargo clippy --workspace --all-targets -- -D warnings`
+  clean (verified this session).
+- **Tests:** **1166 passing / 0 failing** across the workspace
+  (verified this session). The first run flaked once on
+  `solitaire_engine::game_plugin::tests::auto_save_writes_after_30_seconds`
+  — a one-frame `app.update()` test that depends on `time.delta_secs()`
+  on an otherwise-fresh `App`. Reproduced clean on the second run;
+  passes in isolation. Worth tightening if it flakes again, but
+  not blocking the v0.18.0 cut.
+- **Tags on origin:** `v0.9.0` through `v0.17.0`.
+- **CHANGELOG:** v0.18.0 entry drafted in `[Unreleased]`'s slot —
+  ready for tag once build + tests are reverified.
+
+## Where we are
+
+v0.17.0's punch list had four candidates (A–D); two of the three
+non-packaging items shipped in this round:
+
+- **B — "Won previously" HUD indicator:** shipped in `bdac754`.
+- **C — Replay sharing:** shipped in `540869c` ("Copy share link"
+  Stats button + clipboard via `arboard`, in-memory `LastSharedReplayUrl`).
+
+Item **A** (solver-on-`AsyncComputeTaskPool`) shipped *partially* in
+`d489e7a` — the winnable-only seed-selection path is now async with
+cancel-on-replace. The hint path (`H` key,
+`try_solve_with_first_move` / `try_solve_from_state`) is still
+synchronous. The proven `PendingNewGameSeed` template is the
+template for the hint port.
+
+Item **D** (desktop packaging) is unchanged — still gated on
+artwork + signing certs from the player.
+
+The launch experience is also substantially different from v0.17.0:
+on first launch with a saved game the player now sees the Restore
+prompt; on every launch (after splash + restore resolution) they see
+the auto-show Home / mode picker.
+
+### Design direction (unchanged)
+
+- **Tone:** Balatro — chunky readable type, theatrical hierarchy,
+  satisfying micro-interactions.
+- **Palette:** Midnight Purple base + Balatro yellow primary + warm
+  magenta secondary.
+- See `~/.claude/projects/-home-manage-Rusty-Solitare/memory/project_ux_overhaul_2026-04.md`
+  (machine-local).
+
+### Canonical remote
+
+`github.com/funman300/Rusty_Solitaire` is the canonical repo.
+Always push there.
+
+## v0.18.0 (drafted 2026-05-06, not yet tagged)
+
+| Area | Commit | What landed |
+|---|---|---|
+| Restore prompt | `3c7a0eb` + `f863d85` | Welcome-back modal on launch when an in-progress save exists; save preserved across exits while the prompt is unanswered. |
+| Async winnable-only seeds | `d489e7a` | `PendingNewGameSeed` resource + `poll_pending_new_game_seed` running `.before(GameMutation)`. Fixes the worst-case 6 s UI stall on a New Game click. Cancel-on-replace contract covered by tests. |
+| Won-before HUD chip | `bdac754` | Reads `ReplayHistoryResource`; lights `✓ Won before` on tier-2 row when current `(seed, draw_mode, mode)` is in history. |
+| Copy share link | `540869c` | `arboard` clipboard + new Stats button + `SyncProvider::push_replay` returning the share URL. In-memory only; per-session sharing. |
+| MSSC Home picker | `ae40a1d`, `b73d246`, `9fe650f`, `40d6e0a`, `c30b04e`, `d065d49` | Header stats strip (clickable → Profile), draw-mode chips, per-mode score/streak chips, Today's Event callout on Daily, picture-tile 2-up grid with FiraMono-covered glyphs (♣ ◆ ○ ▲ →). |
+| Auto-show Home | `dd63261`, `b7c3a49`, `c497c31` | Auto-shows after splash; gated on Restore prompt; freezes timers (elapsed + Time Attack) while up. |
+| `N` opens real modal | `93660c2` | Removes the "Press N again" double-tap; routes through `ConfirmNewGameScreen`. `Shift+N` retains the bypass. |
+| Win Summary keyboard | `17e0737` | Enter dismisses + starts a fresh deal. |
+| Esc-on-modal fixes | `08b006f`, `d48b948`, `9aa0dd2` | Esc no longer opens Pause underneath the modal it just closed; Home maps Esc to Cancel; Restore maps Esc to Continue; topmost-modal-wins when Profile stacks on Home. |
+| Layout fixes | `a4bc063`, `cc63532` | Settings rows full-width with label-spacer-cluster; popover rows excluded from action-bar auto-fade. |
+| Empty-state copy | `56e2e6f` | Leaderboard / Achievements onboarding hints; volume hotkeys emit toast feedback. |
+| Test prune | `a49a340` | −43 low-value tests; future briefs request behaviour contracts only. |
+| Docs unified-3.0 | `f2f30c8` | Adopts CLAUDE.md / CLAUDE_SPEC.md / CLAUDE_WORKFLOW.md / CLAUDE_PROMPT_PACK.md; trims duplicated rule passages. |
+
+## Open punch list
+
+### Carried forward from v0.17.0
+
+- **Solver-on-`AsyncComputeTaskPool` for the H-key hint** —
+  remaining synchronous solver hot path. The seed-selection port
+  in `d489e7a` is the template: `PendingHintTask` resource, polling
+  system running `.before(GameMutation)`, cancel-on-replace, fall
+  back to the heuristic on inconclusive. Diff should stay scoped
+  to `input_plugin.rs` plus a small `pending_hint.rs`.
+- **Desktop packaging** per `ARCHITECTURE.md §17`. Arch PKGBUILD
+  exists in `/home/manage/solitaire-quest-pkgbuild/` (separate
+  repo). Pending: app icon, macOS `.icns` + notarisation cert,
+  Windows `.ico` + Authenticode cert, AppImage recipe.
+
+### New this round
+
+- **Persistent share link.** `LastSharedReplayUrl` is in-memory only
+  — the player must share within the session of the win. If
+  cross-session sharing turns into a real ask, persist alongside
+  the rolling replay history.
+- **Per-mode artwork.** Picture tiles use Unicode glyphs as
+  placeholders chosen from FiraMono's actual coverage. When real
+  artwork lands, swap each tile's `Text` node for an `Image` node
+  — tile layout, focus order, click handling, and chip rendering
+  are unchanged.
+
+### Process notes (from this round)
+
+- **Test inflation pattern (resolved this round):** older agent
+  briefs reflexively asked for ≥3 tests per feature, producing 43
+  low-value coverage entries on stdlib/serde-derive mechanics. Going
+  forward, ask for tests that pin behaviour contracts or
+  regressions on real bugs only. See
+  `feedback_test_discipline.md` in auto-memory.
+- **Solver async refactor sequencing (worked this round):** rather
+  than porting the whole solver-on-main-thread surface in one PR
+  (the rollback case from before v0.17.0), the
+  `PendingNewGameSeed` work shipped one well-bounded path with two
+  tests covering the happy path and cancel-on-replace. The hint
+  port should follow the same shape.
+
+## Resume prompt
+
+```
+You are a senior Rust + Bevy developer working on Solitaire Quest.
+Working directory: <Rusty_Solitaire clone path on this machine>.
+Branch: master. Direction is OPEN — v0.18.0 has been drafted but
+not tagged: 24 commits past v0.17.0 cover the launch-experience
+round, MSSC Home picker, async winnable-only seeds, Won-before
+HUD, Copy share link, N-key flow rework, Esc-layering fixes, and
+the unified-3.0 Claude rule set.
+
+State: HEAD at v0.17.0-24-gc497c31. Working tree clean.
+CHANGELOG.md has the v0.18.0 entry slotted under [Unreleased].
+
+READ FIRST (in order, before doing anything):
+  1. SESSION_HANDOFF.md  — this file
+  2. CHANGELOG.md        — v0.18.0 draft entry
+  3. CLAUDE.md           — unified-3.0 rule set
+  4. CLAUDE_SPEC.md      — formal architecture spec
+  5. ARCHITECTURE.md     — crate responsibilities + data flow
+  6. ~/.claude/projects/<this-project>/memory/MEMORY.md
+                         — saved feedback / project context
+                           (machine-local; may be missing on a
+                           fresh machine)
+
+DECISION TO ASK THE PLAYER FIRST:
+  A. Tag v0.18.0 — promote `[Unreleased]` to `[0.18.0]` (already
+     done in this session's draft), reverify build + clippy +
+     tests, tag, push. Mechanical close-out.
+  B. Solver-on-AsyncComputeTaskPool for the H-key hint, using the
+     `d489e7a` seed-selection port as template. Last synchronous
+     solver hot path. Smallest delta on the open punch list.
+  C. Desktop packaging — needs artwork + signing certs from the
+     player; can't be driven by the agent alone.
+  D. Persistent share link — store the URL alongside replay
+     history so cross-session sharing works.
+
+WORKFLOW NOTES:
+  - Commits use:
+      git -c user.name=funman300 -c user.email=root@vscode.infinity \
+          commit -m "..."
+  - When attributing playtester feedback in commits/docs, use
+    "Quat" not "Rhys" (saved feedback memory).
+  - Sub-agents stage + verify only; orchestrator commits.
+  - Every commit must pass build / clippy / test before pushing.
+  - Push to GitHub (origin) — that is the canonical remote.
+
+OPEN AT THE START: ask which of A–D. Don't pick unilaterally.
+```