docs: switch asset pipeline notes to AssetServer model

Card faces, card backs, board backgrounds, and the UI font are loaded
via Bevy's AssetServer at startup (see commit fbe984c). The CLAUDE.md
hard rule still claimed cards/backgrounds were rendered procedurally
with no AssetServer, and ARCHITECTURE.md §14 / §20 still described
PNGs and TTFs as embedded via include_bytes!(). Update both docs:

- CLAUDE.md hard rule lists which assets ship in assets/ and notes the
  Option<Res<AssetServer>> fallback used under MinimalPlugins (tests).
- ARCHITECTURE.md §2/§3/§5/§14 rewritten to describe the AssetServer
  loaders for CardImageSet, BackgroundImageSet, and FontResource, and
  the Text2d / solid-colour fallbacks.
- ARCHITECTURE.md §20 decision log replaces the two reversed
  embed-via-include_bytes!() entries with a single entry covering the
  switch to AssetServer plus a note that audio remains embedded.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ARCHITECTURE.md

@@ -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)
+│   │   ├── faces/{RANK}{SUIT}.png   # 52 card faces — xCards @2x artwork (LGPL-3.0)
-│   │   └── backs/back_0.png – back_4.png    # placeholder patterns
+│   │   └── backs/back_0.png – back_4.png    # back_0 = xCards bicycle_blue; back_1–4 are generated patterns
-│   ├── backgrounds/bg_0.png – bg_4.png      # placeholder textures
+│   ├── backgrounds/bg_0.png – bg_4.png      # generated textures
 │   ├── fonts/main.ttf          # FiraMono-Medium (170K, OFL)
 │   └── audio/
 │       ├── card_deal.wav
@@ -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`.
@@ -239,7 +239,7 @@ Done
 |---|---|---|
 | `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 |
@@ -296,7 +296,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
@@ -772,11 +772,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 +1006,5 @@ 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 |
+| 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. xCards @2x faces, 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 |
-| 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 |
+| 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 |

CLAUDE.md

@@ -47,7 +47,9 @@ cargo clippy -p solitaire_core -- -D warnings
 
 - `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.
+- Audio assets are embedded at compile time using `include_bytes!()` in `audio_plugin.rs`.
+- Card faces (52 PNGs in `assets/cards/faces/`), card backs (`assets/cards/backs/back_N.png`), board backgrounds (`assets/backgrounds/bg_N.png`), and the UI font (`assets/fonts/main.ttf`) are loaded at runtime via `AssetServer::load()` and stored as `Handle<Image>`/`Handle<Font>` in the `CardImageSet`, `BackgroundImageSet`, and `FontResource` resources. The `assets/` directory must ship alongside the binary.
+- Asset-loading systems take `Option<Res<AssetServer>>` so they degrade cleanly under `MinimalPlugins` (tests). When `CardImageSet` is absent, `card_plugin` falls back to a `Text2d` rank+suit overlay; when `BackgroundImageSet` is absent, the board falls back to a solid colour.
 - 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.

solitaire_engine/src/events.rs

@@ -4,6 +4,7 @@ use bevy::prelude::Message;
 use solitaire_core::game_state::GameMode;
 use solitaire_core::pile::PileType;
 use solitaire_data::AchievementRecord;
+use solitaire_sync::SyncResponse;
 
 /// Request to move `count` cards from `from` to `to`. Fired by input systems,
 /// consumed by `GamePlugin`.
@@ -78,6 +79,16 @@ pub struct AchievementUnlockedEvent(pub AchievementRecord);
 #[derive(Message, Debug, Clone, Copy, Default)]
 pub struct ManualSyncRequestEvent;
 
+/// Fired by `SyncPlugin` after a pull task resolves and the merged result has
+/// been persisted to disk. `Ok(SyncResponse)` carries the merged payload plus
+/// any `ConflictReport`s the merge produced. `Err(String)` carries a
+/// human-readable failure message (network, auth, serialization, etc.).
+///
+/// UI systems listen for this to refresh views without polling
+/// `SyncStatusResource`. See [ARCHITECTURE.md §4](../../ARCHITECTURE.md).
+#[derive(Message, Debug, Clone)]
+pub struct SyncCompleteEvent(pub Result<SyncResponse, String>);
+
 /// Fired by `InputPlugin` when N is pressed while a game is in progress
 /// but confirmation has not yet been received. The animation plugin shows
 /// a "Press N again to confirm" toast. A second N press within the

solitaire_engine/src/lib.rs

@@ -69,7 +69,7 @@ pub use events::{
     AchievementUnlockedEvent, CardFaceRevealedEvent, CardFlippedEvent, DrawRequestEvent,
     ForfeitEvent, GameWonEvent, HintVisualEvent, InfoToastEvent, ManualSyncRequestEvent,
     MoveRejectedEvent, MoveRequestEvent, NewGameConfirmEvent, NewGameRequestEvent,
-    StateChangedEvent, UndoRequestEvent, XpAwardedEvent,
+    StateChangedEvent, SyncCompleteEvent, UndoRequestEvent, XpAwardedEvent,
 };
 pub use game_plugin::{ConfirmNewGameScreen, GameMutation, GameOverScreen, GamePlugin, GameStatePath};
 pub use help_plugin::{HelpPlugin, HelpScreen};
@@ -88,7 +88,9 @@ pub use resources::{DragState, GameStateResource, HintCycleIndex, SettingsScroll
 pub use selection_plugin::{SelectionHighlight, SelectionPlugin, SelectionState};
 pub use stats_plugin::{StatsPlugin, StatsResource, StatsScreen, StatsUpdate};
 pub use sync_plugin::{SyncPlugin, SyncProviderResource};
-pub use table_plugin::{HintPileHighlight, PileMarker, TableBackground, TablePlugin};
+pub use table_plugin::{
+    BackgroundImageSet, HintPileHighlight, PileMarker, TableBackground, TablePlugin,
+};
 pub use time_attack_plugin::{
     TimeAttackEndedEvent, TimeAttackPlugin, TimeAttackResource, TIME_ATTACK_DURATION_SECS,
 };

solitaire_engine/src/sync_plugin.rs

@@ -22,10 +22,10 @@ use solitaire_data::{
     save_achievements_to, save_progress_to, save_stats_to, AchievementRecord, PlayerProgress,
     StatsSnapshot, SyncError, SyncProvider,
 };
-use solitaire_sync::{merge, SyncPayload};
+use solitaire_sync::{merge, SyncPayload, SyncResponse};
 
 use crate::achievement_plugin::{AchievementsResource, AchievementsStoragePath};
-use crate::events::ManualSyncRequestEvent;
+use crate::events::{ManualSyncRequestEvent, SyncCompleteEvent};
 use crate::progress_plugin::{ProgressResource, ProgressStoragePath};
 use crate::resources::{SyncStatus, SyncStatusResource};
 use crate::stats_plugin::{StatsResource, StatsStoragePath};
@@ -94,6 +94,7 @@ impl Plugin for SyncPlugin {
             .init_resource::<PullTaskResult>()
             .init_resource::<PullTask>()
             .add_message::<ManualSyncRequestEvent>()
+            .add_message::<SyncCompleteEvent>()
             .add_systems(Startup, start_pull)
             .add_systems(Update, (poll_pull_result, handle_manual_sync_request))
             .add_systems(Last, push_on_exit);
@@ -161,6 +162,7 @@ fn poll_pull_result(
     achievements_path: Res<AchievementsStoragePath>,
     mut progress: ResMut<ProgressResource>,
     progress_path: Res<ProgressStoragePath>,
+    mut complete_writer: MessageWriter<SyncCompleteEvent>,
 ) {
     let Some(task) = task_res.0.as_mut() else {
         return;
@@ -173,7 +175,7 @@ fn poll_pull_result(
     match result {
         Ok(remote) => {
             let local = build_payload(&stats.0, &achievements.0, &progress.0);
-            let (merged, _conflicts) = merge(&local, &remote);
+            let (merged, conflicts) = merge(&local, &remote);
 
             // Persist merged state atomically.
             if let Some(p) = &stats_path.0
@@ -190,10 +192,17 @@ fn poll_pull_result(
                 }
 
             // Update in-world resources.
-            stats.0 = merged.stats;
+            let now = Utc::now();
-            achievements.0 = merged.achievements;
+            stats.0 = merged.stats.clone();
-            progress.0 = merged.progress;
+            achievements.0 = merged.achievements.clone();
-            status.0 = SyncStatus::LastSynced(Utc::now());
+            progress.0 = merged.progress.clone();
+            status.0 = SyncStatus::LastSynced(now);
+
+            complete_writer.write(SyncCompleteEvent(Ok(SyncResponse {
+                merged,
+                server_time: now,
+                conflicts,
+            })));
         }
         Err(SyncError::UnsupportedPlatform) => {
             // No backend configured — not an error, just leave status as Idle.
@@ -207,7 +216,8 @@ fn poll_pull_result(
                 SyncError::Serialization(_) => format!("Unexpected server response: {e}"),
                 SyncError::UnsupportedPlatform => unreachable!("handled above"),
             };
-            status.0 = SyncStatus::Error(msg);
+            status.0 = SyncStatus::Error(msg.clone());
+            complete_writer.write(SyncCompleteEvent(Err(msg)));
         }
     }
 }