docs: add comprehensive model card with training details, usage instructions, and provenance info

README.md

@@ -1,52 +1,189 @@
-# Pixel Art LoRA Test Samples
+---
+language:
+- en
+license: apache-2.0
+library_name: diffusers
+tags:
+- lora
+- flux
+- pixel-art
+- game-asset
+- sprite
+- character-design
+- text-to-image
+- FLUX.2-klein-4B
+base_model: black-forest-labs/FLUX.2-klein-4B
+datasets:
+- Limbicnation/pixel-art-character
+pipeline_tag: text-to-image
+widget:
+- text: "pixel art sprite, a brave knight in shining armor holding a sword, game asset, transparent background"
+  output:
+    url: samples/01_a_brave_knight_in_shining_armor_holding_.png
+- text: "pixel art sprite, a fire-breathing dragon with red scales, game asset, transparent background"
+  output:
+    url: samples/06_a_fire-breathing_dragon_with_red_scales_.png
+- text: "pixel art sprite, a cute slime monster, blue and bouncy, game asset, transparent background"
+  output:
+    url: samples/07_a_cute_slime_monster_blue_and_bouncy.png
+---
+
+# Pixel Art Sprite LoRA for FLUX.2-klein-4B
+
+A LoRA adapter trained on FLUX.2-klein-4B for generating pixel art character sprites. Optimized for game-ready assets with transparent backgrounds.
+
+## Highlights
+
+- **4-step inference** — FLUX.2-klein is distilled, so generation is fast
+- **512x512 RGBA** output with transparent backgrounds
+- **CC0 training data** — 100% public domain, no copyright concerns
+- **Game-ready** — designed for Godot, Unity, and other engines
+
+## Quick Start
+
+### Trigger Words
+
+Always include in your prompt:
+
+```
+pixel art sprite, [your character description], game asset, transparent background
+```
+
+**Style modifiers:** `16-bit pixel art`, `32-bit pixel art`, `chibi`
+
+### Inference Parameters
+
+| Parameter | Value |
+|-----------|-------|
+| Steps | 4 |
+| CFG Scale | 1.0 |
+| Resolution | 512x512 |
+| Sampler | Euler |
+
+### Python (Diffusers)
+
+> Requires `diffusers >= 0.37.0.dev0` (install from git main)
 
-**Generated:** 2026-02-08 01:20 UTC
+```python
+import torch
+from diffusers import Flux2KleinPipeline
 
-**Model:** [Limbicnation/pixel-art-lora](https://huggingface.co/Limbicnation/pixel-art-lora)
+# Load base model + LoRA
+pipe = Flux2KleinPipeline.from_pretrained(
+    "black-forest-labs/FLUX.2-klein-4B",
+    torch_dtype=torch.bfloat16,
+    low_cpu_mem_usage=False,
+)
+pipe.load_lora_weights("Limbicnation/pixel-art-lora")
+pipe.to("cuda")
 
-**Base Model:** [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)
+image = pipe(
+    "pixel art sprite, a brave knight in shining armor, game asset, transparent background",
+    num_inference_steps=4,
+    guidance_scale=1.0,
+    height=512,
+    width=512,
+).images[0]
 
-**Samples Location:** `samples/` folder in this repository
+image.save("knight.png")
+```
 
-## Generation Parameters
+### ComfyUI
 
-- **Steps:** 4
-- **CFG Scale:** 1.0
-- **Seed:** 42
-- **Resolution:** 512x512
-- **Device:** cuda
+1. Download the LoRA weights:
+   ```bash
+   huggingface-cli download Limbicnation/pixel-art-lora \
+       pytorch_lora_weights.safetensors \
+       --local-dir ./models/loras/
+   ```
+2. Load FLUX.2-klein-4B as the base checkpoint
+3. Add a **Load LoRA** node, point to `pytorch_lora_weights.safetensors`
+4. Set LoRA strength: **0.85 - 1.4** (tested range)
+5. Use trigger words in your positive prompt
+
+A sample workflow is included: [`comfyui_workflow.json`](./comfyui_workflow.json)
 
 ## Sample Gallery
 
-| # | Preview | Prompt |
-|---|---------|--------|
-| 1 | ![Sample 1](./samples/01_a_brave_knight_in_shining_armor_holding_.png) | pixel art sprite, a brave knight in shining armor holding a ... |
-| 2 | ❌ Failed | pixel art sprite, a mystical wizard with a long beard and gl... |
-| 3 | ![Sample 3](./samples/03_an_elven_archer_with_bow_and_quiver_wear.png) | pixel art sprite, an elven archer with bow and quiver, weari... |
-| 4 | ![Sample 4](./samples/04_a_fierce_orc_warrior_with_battle_axe_and.png) | pixel art sprite, a fierce orc warrior with battle axe and a... |
-| 5 | ![Sample 5](./samples/05_a_dwarf_paladin_with_war_hammer_and_heav.png) | pixel art sprite, a dwarf paladin with war hammer and heavy ... |
-| 6 | ![Sample 6](./samples/06_a_fire-breathing_dragon_with_red_scales_.png) | pixel art sprite, a fire-breathing dragon with red scales an... |
-| 7 | ![Sample 7](./samples/07_a_cute_slime_monster_blue_and_bouncy.png) | pixel art sprite, a cute slime monster, blue and bouncy, gam... |
-| 8 | ![Sample 8](./samples/08_a_skeletal_warrior_with_rusty_sword_unde.png) | pixel art sprite, a skeletal warrior with rusty sword, undea... |
-| 9 | ![Sample 9](./samples/09_a_majestic_unicorn_with_rainbow_mane.png) | pixel art sprite, a majestic unicorn with rainbow mane, game... |
-| 10 | ![Sample 10](./samples/10_a_dark_vampire_lord_with_cape_and_fangs.png) | pixel art sprite, a dark vampire lord with cape and fangs, g... |
-| 11 | ![Sample 11](./samples/11_a_space_marine_in_power_armor_with_laser.png) | pixel art sprite, a space marine in power armor with laser r... |
-| 12 | ![Sample 12](./samples/12_a_cyberpunk_hacker_with_neon_implants_an.png) | pixel art sprite, a cyberpunk hacker with neon implants and ... |
-| 13 | ![Sample 13](./samples/13_a_cute_robot_companion_with_glowing_eyes.png) | pixel art sprite, a cute robot companion with glowing eyes, ... |
-| 14 | ![Sample 14](./samples/14_a_zombie_survivor_with_baseball_bat_and_.png) | pixel art sprite, a zombie survivor with baseball bat and ba... |
-| 15 | ![Sample 15](./samples/15_a_ninja_assassin_in_black_outfit_with_ka.png) | pixel art sprite, a ninja assassin in black outfit with kata... |
+| Preview | Prompt |
+|---------|--------|
+| ![Knight](./samples/01_a_brave_knight_in_shining_armor_holding_.png) | pixel art sprite, a brave knight in shining armor holding a sword |
+| ![Archer](./samples/03_an_elven_archer_with_bow_and_quiver_wear.png) | pixel art sprite, an elven archer with bow and quiver |
+| ![Orc](./samples/04_a_fierce_orc_warrior_with_battle_axe_and.png) | pixel art sprite, a fierce orc warrior with battle axe |
+| ![Dragon](./samples/06_a_fire-breathing_dragon_with_red_scales_.png) | pixel art sprite, a fire-breathing dragon with red scales |
+| ![Slime](./samples/07_a_cute_slime_monster_blue_and_bouncy.png) | pixel art sprite, a cute slime monster, blue and bouncy |
+| ![Skeleton](./samples/08_a_skeletal_warrior_with_rusty_sword_unde.png) | pixel art sprite, a skeletal warrior with rusty sword |
+| ![Unicorn](./samples/09_a_majestic_unicorn_with_rainbow_mane.png) | pixel art sprite, a majestic unicorn with rainbow mane |
+| ![Vampire](./samples/10_a_dark_vampire_lord_with_cape_and_fangs.png) | pixel art sprite, a dark vampire lord with cape and fangs |
+| ![Marine](./samples/11_a_space_marine_in_power_armor_with_laser.png) | pixel art sprite, a space marine in power armor |
+| ![Cyberpunk](./samples/12_a_cyberpunk_hacker_with_neon_implants_an.png) | pixel art sprite, a cyberpunk hacker with neon implants |
+| ![Robot](./samples/13_a_cute_robot_companion_with_glowing_eyes.png) | pixel art sprite, a cute robot companion with glowing eyes |
+| ![Ninja](./samples/15_a_ninja_assassin_in_black_outfit_with_ka.png) | pixel art sprite, a ninja assassin in black outfit with katana |
 
+**14/15 samples generated successfully** (1 failed due to content filter)
 
-## Summary
+## Training Details
 
-- **Total:** 15
-- **Success:** 14 ✅
-- **Failed:** 1
+| Parameter | Value |
+|-----------|-------|
+| Base model | `black-forest-labs/FLUX.2-klein-4B` |
+| LoRA rank | 64 |
+| LoRA alpha | 128 |
+| rsLoRA | Yes |
+| Dtype | bfloat16 |
+| Steps | 1000 |
+| Batch size | 1 |
+| Gradient accumulation | 4 |
+| Learning rate | 1e-4 |
+| LR scheduler | Cosine with restarts |
+| Optimizer | AdamW 8-bit |
+| Resolution | 512x512 |
+| Dataset | 500 images (CC0 curated + synthetic) |
 
-## Trigger Words
+**Final loss:** ~1.8 - 2.0 (stable convergence)
 
-For best results, always include: `pixel art sprite, game asset, transparent background`
+Full training config: [`config.yaml`](./config.yaml)
 
----
+## Dataset & Provenance
+
+- **Training dataset:** [Limbicnation/pixel-art-character](https://huggingface.co/datasets/Limbicnation/pixel-art-character) (1,010 images)
+- **License:** All training images are CC0 (public domain) — no copyright restrictions
+- **Provenance:** Full manifest with source attribution available in the dataset repo
+- **Legal analysis:** Synthetic training data compliant for commercial use
+
+This model was trained with full data provenance tracking. All source images are CC0 public domain, making the outputs safe for commercial game development, Steam releases, and B2B studio use.
+
+## Architecture Notes
+
+FLUX.2-klein-4B uses a different architecture from FLUX.1:
+
+- **Text encoder:** Qwen3 (not CLIP+T5)
+- **Pipeline class:** `Flux2KleinPipeline` (not `FluxPipeline`)
+- **VAE:** `AutoencoderKLFlux2`
+- **Distilled:** 4-step inference with guidance scale 1.0
+
+> You must use `diffusers >= 0.37.0.dev0` (install from git main branch). The released 0.36.x does not include `Flux2KleinPipeline`.
+
+## License
+
+This LoRA adapter is released under [Apache 2.0](./LICENSE).
+
+The base model (FLUX.2-klein-4B) is also Apache 2.0 licensed.
+
+## Citation
+
+```bibtex
+@misc{pixel-art-lora-2026,
+  title={Pixel Art Sprite LoRA for FLUX.2-klein-4B},
+  author={Limbicnation},
+  year={2026},
+  url={https://huggingface.co/Limbicnation/pixel-art-lora}
+}
+```
+
+## Links
 
-*Generated with Hugging Face Diffusers & FLUX.2-klein-4B*
+- **Model:** [Limbicnation/pixel-art-lora](https://huggingface.co/Limbicnation/pixel-art-lora)
+- **Dataset:** [Limbicnation/pixel-art-character](https://huggingface.co/datasets/Limbicnation/pixel-art-character)
+- **Base model:** [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)
+- **Training code:** [Limbicnation/SpriteForge](https://github.com/Limbicnation/SpriteForge)