a3minilab · tutorials

Guided tutorials ("kits") for a3minilab, served from GitHub Pages.

The app fetches index.json, shows the gallery, and downloads the kits the user picks. Publishing a new tutorial does not require rebuilding the app or going through the Play Store.

Layout

├── kits/                     # the only files edited by hand
│   ├── spaceship.json        #   steps + version + min_app_version
│   ├── spaceship_en.json     #   kit metadata + texts (English is the fallback)
│   ├── spaceship_es.json     #   kit metadata + texts
│   └── spaceship.png         #   32x32 cover
├── tools/build_index.py      # builds index.json and the cover sheet
└── .github/workflows/publish.yml

index.json and covers-<hash>.png are generated on every push and are not committed.

Adding a tutorial

1. Write the four files in kits/.
2. Validate them from the app repo (see below).
3. git push. The Action rebuilds the index and publishes.

Validation

The validator does not live here: it sits in the app repo, because it checks every step's anchors against the real scenes. If a button gets renamed, it catches it — a list copied into this repo would go stale without anyone noticing.

# from the app repo root, with this repo checked out next to it
python3 a3-engine/tools/validate_kits.py ../a3minilab-tutorials/kits

It checks step numbering, known step and check types, that anchors exist, complete texts in both languages, well-formed autofixes, and the cover image. Run it before pushing: there is no safety net here.

Why the index is generated

The index carries no information of its own: title, description, version and minimum app version all come from inside the kit files. If nothing is written in two places, nothing can fall out of sync.

The cover sheet carries its hash in the filename (covers-f7b6ad5e.png). When the content changes so does the URL, so a stale cached sheet can never pair the wrong cover with the wrong kit.

min_app_version

Every kit declares which app version it needs, and the app filters out anything it cannot run. A tutorial using a check or a button that does not exist in the installed version would strand the user on an impossible step.

Bump it whenever the kit uses something new: a recently added check, an anchor from a screen that changed, a new autofix type.

Building the index locally

pip install Pillow
python3 tools/build_index.py