chore: move app skill in-repo + AGENTS.md

- Migrates tactility-app-development from ~/.hermes/skills/ into .claude/skills/ for repo co-location - Adds AGENTS.md with local workstation context, hardware table, board-direct build/env wrapper (PYTHONPATH fix), ELF missing-symbol triage, app patterns (immersive, QVGA rail, tutorial 2-row, GameKit bubbling, screenshot rate-limit), and skill index Refs: personal Gitea mirror
2026-07-17 09:51:20 -04:00
parent d976595879
commit e68909d64d
15 changed files with 1478 additions and 0 deletions
@@ -0,0 +1,46 @@
+# Per-Book Offline Bible Assets
+
+Source: https://github.com/sajeevavahini/bibles — Zefania XML `World English Bible.xml` ~4.8MB, format `XMLBIBLE/BIBLEBOOK/CHAPTER/VERS` attrs `bnumber/bname/cnumber/vnumber`.
+
+## Problem
+- 4.8MB XML → 3.8MB blob + 304KB idx monolith = too big for RAM, packaging bloats `.app` to 4.2MB monolith load.
+- Device has ~8MB PSRAM but LVGL/lwIP compete; loading whole bible at once OOM-prone.
+
+## Solution: per-book split
+
+Output `assets/bible/`:
+- `books.json`: `[{bnumber, bname, verses, chapters}, ...]` 66 entries
+- `<bnum>.bin` (01.bin..66.bin): concatenated NUL-terminated UTF-8 verse strings
+- `<bnum>.idx`: binary: header 8 bytes: magic `BIBK` ascii, version u16 (1), count u32; then per entry 8 bytes: `offset u32 LE, cnum u16 LE, vnum u16 LE` sorted by chapter/verse.
+
+Worst book: Psalms 19.bin ~220KB, still fits. Total ~4.1MB split but loaded one at a time → RAM tiny.
+
+## Converter
+
+`Apps/BibleVerse/tools/convert_bible.py` (also template):
+
+Usage:
+```bash
+python3 tools/convert_bible.py /path/to/World\ English\ Bible.xml assets/bible/
+# or fetch then convert
+```
+
+Implementation sketch (see templates/convert_bible.py):
+- xml.etree.ElementTree iterative parse `BIBLEBOOK` to keep memory low.
+- Accumulate bin buffer + idx entries per book.
+- Write books.json last.
+
+## Hybrid resolution on device
+
+```c
+// 1. Try embedded A: assets via tt_app_get_assets_path
+// 2. Fallback scan /sdcard/bibles/WEB/ same binary format for user-provided translations
+// 3. build target: load BookInfo array, then on demand load_book(bnumber) frees previous.
+```
+
+## Verify packaging
+
+```bash
+tar tvf build/BibleVerse.app | grep "\.bin" | wc -l  # expect 66
+ls -lh assets/bible/*.bin | sort -k5 -hr | head
+```