Update README.md

README.md

@@ -1,3 +1,222 @@
 ---
-license: cc0-1.0
+license: mit
+library_name: pytorch
+tags:
+- chess
+- chess-engine
+- stockfish
+- imitation-learning
+- policy-distillation
+- value-network
+- uci
+- lichess-bot
 ---
+
+# JoeyEngine-30M
+
+**JoeyEngine-30M** is a lightweight neural chess engine distilled from Stockfish-labeled positions.
+
+It is designed to be simple to run, easy to plug into `lichess-bot`, and useful as a compact baseline for **search-free neural chess play**.
+
+```text
+Model:        30M-parameter policy/value CNN
+Training:     Stockfish imitation learning
+Dataset:      10M positions
+Labels:       depth-10 Stockfish, MultiPV=5
+Inference:    no search, no opening book, no tablebase
+Interface:    UCI-compatible
+```
+
+---
+
+## Links
+
+- **Model:** https://huggingface.co/Joeyfully/chess-stockfish-il-10m-d10-mpv5
+- **Dataset:** https://huggingface.co/datasets/Joeyfully/chess-stockfish-il-10m-d10-mpv5
+- **Lichess bot:** https://lichess.org/@/Joey_ChessEngine
+
+---
+
+## Model Tags
+
+```text
+neural chess engine
+Stockfish distillation
+imitation learning
+policy/value network
+search-free chess engine
+UCI engine
+lichess-bot compatible
+PyTorch
+```
+
+---
+
+## Performance
+
+JoeyEngine is evaluated as a **pure neural engine**:
+
+```text
+No alpha-beta search
+No MCTS
+No opening book
+No endgame tablebase
+One neural forward pass per move
+```
+
+### Offline test set
+
+| Metric | Value |
+|---|---:|
+| Test positions | 500,000 |
+| Stockfish top-1 accuracy | 47.12% |
+| Stockfish top-3 accuracy | 77.59% |
+| Stockfish top-5 accuracy | 87.78% |
+| Value correlation | 0.9401 |
+| Test loss | 2.0580 |
+
+### Engine match diagnostics
+
+These are preliminary diagnostics, not official Elo ratings.
+
+| Opponent | Time Control | Games | Score |
+|---|---:|---:|---:|
+| Stockfish UCI_Elo=1500 | 60+0.6 | 20 | 60.0% |
+| Stockfish UCI_Elo=1500 | 10+0.1 | 100 | 70.0% |
+| Stockfish UCI_Elo=1800 | 10+0.1 | 100 | 34.0% |
+
+Observed behavior:
+
+```text
+Stronger at short time controls
+Strong in direct attacks and mating patterns
+Weaker in long forcing lines and endgame conversion
+```
+
+---
+
+## Quick Start
+
+Install dependencies:
+
+```bash
+pip install torch numpy python-chess
+```
+
+Run the UCI engine:
+
+```bash
+python uci_engine.py --ckpt best_engine.pt --device cpu
+```
+
+Manual UCI test:
+
+```text
+uci
+isready
+position startpos
+go movetime 1000
+quit
+```
+
+Expected style of output:
+
+```text
+id name JoeyStage1StockfishDistill
+id author Joey
+uciok
+readyok
+bestmove e2e4
+```
+
+---
+
+## Use with lichess-bot
+
+JoeyEngine can be used directly as a custom UCI engine in `lichess-bot`.
+
+Example layout:
+
+```text
+lichess-bot/
+  engines/
+    JoeyEngine/
+      joey_engine.sh
+      uci_engine.py
+      model.py
+      common_chess.py
+      best_engine.pt
+```
+
+Example `joey_engine.sh`:
+
+```bash
+#!/usr/bin/env bash
+cd "$(dirname "$0")"
+export OMP_NUM_THREADS=1
+export MKL_NUM_THREADS=1
+export OPENBLAS_NUM_THREADS=1
+export NUMEXPR_NUM_THREADS=1
+export NUMEXPR_MAX_THREADS=1
+exec /path/to/python -u uci_engine.py --ckpt best_engine.pt --device cpu
+```
+
+Example `config.yml` engine block:
+
+```yaml
+engine:
+  dir: "./engines/JoeyEngine"
+  name: "joey_engine.sh"
+  debug: false
+  working_dir: "./engines/JoeyEngine"
+  protocol: "uci"
+  ponder: false
+  uci_options: {}
+  silence_stderr: false
+```
+
+For pure JoeyEngine evaluation, disable external move sources:
+
+```yaml
+online_moves:
+  chessdb_book:
+    enabled: false
+  lichess_cloud_analysis:
+    enabled: false
+  lichess_opening_explorer:
+    enabled: false
+  online_egtb:
+    enabled: false
+
+lichess_bot_tbs:
+  syzygy:
+    enabled: false
+  gaviota:
+    enabled: false
+```
+
+---
+
+## Recommended Files
+
+```text
+best_engine.pt      # inference checkpoint
+uci_engine.py       # UCI wrapper
+model.py            # model definition
+common_chess.py     # board/action utilities
+requirements.txt
+README.md
+```
+
+---
+
+## Citation
+
+```bibtex
+@misc{joeyengine30m2026,
+  title        = {JoeyEngine-30M: Stockfish Policy/Value Distillation for Search-Free Neural Chess Play},
+  author       = {Joey},
+  year         = {2026},
+  howpublished = {https://huggingface.co/Joeyfully/chess-stockfish-il-10m-d10-mpv5}
+}
+```