From 617e8ef543c7d4cdd506777f87a3d31064b65273 Mon Sep 17 00:00:00 2001 From: omachy form the big pc republic Date: Sun, 13 Sep 2026 22:55:54 +0100 Subject: [PATCH] AGENTS.md: agent guidance, crown-control caveats; crown work moves to this branch --- AGENTS.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..31116a0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,70 @@ +# AGENTS.md — vela-snake + +Guidance for AI agents working on this repo. Humans can read it too, we don't judge. + +## What this is + +Textured Snake for the Xiaomi Watch S4 (round 466px screen, Vela quickapp). +Package `com.ilias.snake`. Source of truth for releases: +https://gitea.oimcloud.myaddr.tools/oiwmiodev/vela-snake (Big Intelligence group). +Upstream codex-bot/vela-snake is read-only for us (no write permission). + +## Hard rules + +- Never commit `sign/*.pem` (gitignored on purpose). Currently the toolkit's + default debug keys are used; if real keys appear, keep them out of git. +- Never edit files under `node_modules/`. The toolkit is locked at aiot-toolkit + 2.0.5; do not upgrade it casually (release uses plain JS, not JSC/protobuf). +- Tests must pass before any commit: `npm test` (pure Node, no watch needed). +- Bump `versionName`/`versionCode` in `src/manifest.json` for any release. + Hotfixes: `0.9-Hotfix.1` style, versionCode still increments (integer only). +- The user hates em dashes. Don't use them in docs, commits or comments. + +## Crown control (the fragile part) + +The Vela firmware does NOT expose crown events to quickapps (verified by +firmware string analysis, see docs/CROWN.md). Crown rotation arrives only as +scroll deltas on the focused scroll container. The page is a full-screen +vertical `scroll` with the dial centered; `onscroll` converts accumulated +deltas into queued 90-degree turns (`CROWN_STEP_PX`, 40px per turn) and snaps +the scroller back to center (`scrollTo({top: 233})`). + +Known failure mode (issue oiwmiodev/vela-snake#1): the game can still scroll +away, likely because momentum scrolling outlives the snap-back or onShow's +scrollTo runs before layout. Any fix must keep: swipe steering working, the +dial visually pinned, reversals impossible. If scroll-delta extraction proves +unreliable on hardware, the fallback is accepting codex-bot issue #2's +conclusion (swipe-only input) and removing the scroll wrapper. + +## Layout invariants + +- Dial/board: 466px screen, board at 49px offset, 368px circle, 32px cells, + 11x11 grid, 89 legal cells (circular mask, see src/common/snake.js ARENA). +- Scroll content height = 932px (233px padding each side), center offset 233. +- Overlays fit the watch chord; no legal cell is ever covered by HUD/footer. +- No CSS transforms anywhere (tests assert this); tiles are positioned with + left/top only. + +## Testing + +`npm test` runs snake logic, piece classification, page wiring (including the +crown scroll path), upgrade regressions, numeric layout, randomized property +tests and art checks. When fixing a bug, add a failing test first, then fix. +Node tests are not device tests: behavior on the actual watch is the only +final proof, and the user is the one with the watch. + +## Release checklist + +1. All tests green. +2. `src/manifest.json` version bumped. +3. `npm run release`, verify dist/com.ilias.snake.release..rpk exists. +4. Commit + push to origin (oiwmiodev/vela-snake). +5. `tea releases create --repo oiwmiodev/vela-snake --tag v ...` and + attach the rpk with `tea releases assets create`. Download the asset back + and byte-compare before claiming success. +6. Release notes: real changelog, never "see commit history". + +## Git + +Commit as: `git -c user.name='omachy form the big pc republic' -c +user.email='oamrchyt@bigpc.com'`. Pushes go to origin (the org repo).