From f05cbf90b602947a5691e1fb75a21b1e9cfbebc0 Mon Sep 17 00:00:00 2001
From: Lucian Mogosanu <lucian@mogosanu.ro>
Date: Mon, 29 Jun 2026 20:43:05 +0300
Subject: [PATCH] Add quickstart guide for tools

---
 tools/README.md            |   48 ++++++++++++++++++++++++++++++++++++++++++++
 tools/openpt/build.py      |    3 ++-
 tools/openpt/decode_vga.py |    3 ++-
 tools/openpt/verify.py     |    3 ++-
 4 files changed, 54 insertions(+), 3 deletions(-)
 create mode 100644 tools/README.md

diff --git a/tools/README.md b/tools/README.md
new file mode 100644
index 0000000..f346165
--- /dev/null
+++ b/tools/README.md
@@ -0,0 +1,48 @@
+# openpt tools — getting started
+
+Pure Python 3, no dependencies. **Run from the repo root** (`openpt/`, the dir
+that holds both `tools/` and `PIZZA/`), using the module path `tools.openpt.<cmd>`.
+Paths are relative to the repo root, so the defaults (`PIZZA`, `artifacts`) work
+with no args.
+
+```sh
+cd ~/src/openpt      # repo root
+```
+
+## Verify the formats
+
+Decode every shipped `.VGA` and confirm each matches its declared size:
+
+```sh
+python3 -m tools.openpt.verify PIZZA
+```
+
+Expected: `145/145` files with header `size == filesize-8`, and the RLE bias
+probe reporting `lit_bias=1 run_bias=1 -> exact=145`.
+
+## Regenerate all artifacts
+
+Decode every `.VGA` to a grayscale PGM (gray = raw palette index) under
+`artifacts/vga/`:
+
+```sh
+python3 -m tools.openpt.build PIZZA artifacts
+```
+
+## Decode a single image
+
+Grayscale (palette-independent — good for checking geometry):
+
+```sh
+python3 -m tools.openpt.decode_vga PIZZA/Z/ZB1.VGA out.pgm --pgm
+```
+
+Color, using palette N from the palette bank:
+
+```sh
+python3 -m tools.openpt.decode_vga PIZZA/GFX/BACK1.VGA out.ppm \
+    --palette PIZZA/GFX/PALETTE.E --pal 0
+```
+
+Output is PNM (PGM/PPM) — open with any image viewer. (The correct palette per
+image is still an open question; see ../CHECKLIST.md.)
diff --git a/tools/openpt/build.py b/tools/openpt/build.py
index 82e7eaf..bd0ae51 100644
--- a/tools/openpt/build.py
+++ b/tools/openpt/build.py
@@ -5,7 +5,8 @@ Currently: decode every .VGA image to a palette-independent grayscale PGM
 (gray = raw palette index) under artifacts/vga/. As more formats are reversed,
 add their regeneration here.
 
-  python3 -m openpt.build [PIZZA_DIR] [ARTIFACTS_DIR]
+Run from the repo root:
+  python3 -m tools.openpt.build [PIZZA_DIR] [ARTIFACTS_DIR]
 """
 
 import glob
diff --git a/tools/openpt/decode_vga.py b/tools/openpt/decode_vga.py
index 1f8ffa5..9386eb4 100644
--- a/tools/openpt/decode_vga.py
+++ b/tools/openpt/decode_vga.py
@@ -1,6 +1,7 @@
 """CLI: decode a .VGA image to PNM.
 
-  python3 -m openpt.decode_vga <file.vga> <out> [--pgm] [--palette F.E] [--pal N]
+Run from the repo root:
+  python3 -m tools.openpt.decode_vga <file.vga> <out> [--pgm] [--palette F.E] [--pal N]
 
 Default output is PPM (color) using palette N from gfx/palette.e. With --pgm,
 or when no palette is given, output a PGM where the gray value is the raw
diff --git a/tools/openpt/verify.py b/tools/openpt/verify.py
index db4ce66..5522eca 100644
--- a/tools/openpt/verify.py
+++ b/tools/openpt/verify.py
@@ -3,7 +3,8 @@
 For each gfx/*.vga and z/*.vga: read header (w,h,size), confirm size == filesize-8,
 decode the payload, and check the decoded length reaches width*height. We probe
 the four plausible count-bias combinations so the *data* tells us the exact
-semantics rather than us guessing. Run:  python3 -m openpt.verify <PIZZA dir>
+semantics rather than us guessing. Run from the repo root:
+  python3 -m tools.openpt.verify [PIZZA dir]
 """
 
 import glob
-- 
1.7.10.4