Upload TUTORIAL.md with huggingface_hub

TUTORIAL.md

@@ -0,0 +1,113 @@
+# 🎨 PXG-Tiny — 5-Minute Tutorial
+
+Turn plain English into 16×16 pixel-art sprites, fully offline.
+*By Chowdhury Tarul Ahsan — tarulahsan@gmail.com*
+
+---
+
+## 1. Install (30 seconds)
+
+```bash
+# Python 3.9+ — only two libraries, no torch, no GPU
+pip install numpy pillow
+```
+
+Unzip the release anywhere. You get this layout:
+
+```
+pxg-tiny/
+├── cli.py              ← command-line app
+├── weights/            ← the trained model (~1 MB)
+├── src/pxg_tiny/       ← inference library (pure NumPy)
+├── samples/gallery/    ← sprites made by the final model
+└── tests/              ← pytest suite
+```
+
+## 2. Your first sprite (10 seconds)
+
+```bash
+python3 cli.py "a golden sword, glowing" -o sword.png
+```
+
+Done — `sword.png` is a crisp 128×128 sprite (16×16 pixels at 8× zoom,
+transparent background).
+
+## 3. What can I ask for?
+
+**Objects (23 families):** sword · dagger · shield · staff · potion · vial ·
+chest · coin · gem · key · apple · bread · oak tree · pine tree · bush ·
+rock · grass/stone/water tile · fireball · house
+
+**Attributes that actually change pixels:**
+
+| Say | Effect |
+|---|---|
+| `golden / iron / crystal / ruby / emerald / wooden / copper` | recolors the material |
+| `upright` / `lying sideways` | rotates key/key/sword orientation |
+| `glowing` | adds white specular shine |
+| `with moss` / `with berries` / `autumn` | adds the detail |
+| `big` / `small` | scales fireballs |
+| `slate roof` / `terracotta roof` | house roof color |
+
+Free phrasing is fine — *“one sword of the crystal kind”*, *“a sword made of
+pure iron”*, *“cottage with terracotta roof”* all work.
+
+## 4. Variations & sprite sheets
+
+```bash
+python3 cli.py "an iron chest" --variations 4 --sheet variants.png
+```
+
+One PNG containing 4 sampled takes on your prompt — perfect for picking a
+favorite or filling a tileset row.
+
+## 5. Ask-first mode (chatbot style)
+
+```bash
+python3 cli.py --ask "can you animate a walking cycle?"
+# → refusal: "i only make 16x16 pixel-art sprites ... no photos, 3d,
+#    animation files, logos or other resolutions."
+
+python3 cli.py --ask "draw a blorp"
+# → clarify: "i don't know that object yet. i can draw: sword, dagger, ..."
+```
+
+The model knows what it doesn't know — it asks instead of hallucinating.
+
+## 6. Python API
+
+```python
+from pxg_tiny.pipeline import PXGPipeline
+
+pipe = PXGPipeline()                     # loads ./weights
+
+grid, meta = pipe.generate_pixels("a ruby potion that glows", seed=7)
+print(meta)                              # {'gate': 'accept', 'attempt': 0, ...}
+
+# raw 16x16 palette-index grid if you want the pixels yourself:
+# grid[y][x] == 0 → transparent, 1..31 → palette color
+
+msg = PXGPipeline.ask("a 4k photo of a cat")   # → refusal message string
+```
+
+Deterministic: same prompt + same seed ⇒ same sprite, forever, on any machine.
+
+## 7. Batch generation
+
+```bash
+cat prompts.txt
+# golden dagger, upright
+# slim vial of the slime kind
+python3 cli.py --sheet-from-prompts prompts.txt --outdir sprites/
+```
+
+## 8. Troubleshooting
+
+| Symptom | Meaning | Fix |
+|---|---|---|
+| `"gate": "clarify"` | object/attribute unknown | pick from the list it gives you |
+| `"gate": "refuse"` | out of scope (3D/photo/animation/other sizes) | rephrase as a 16×16 sprite |
+| `"gate": "accept_degraded"` | sprite returned but a check stayed red after 8 tries | usually still usable; try another seed |
+| wrong material color | rare sampling drift | retry, or bump `--seed` |
+
+*Everything runs 100% locally — no network, no accounts, no API keys.*