@olegkoval/agent-skills 1.19.0 → 1.20.0

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/references/simulator.md

@@ -0,0 +1,146 @@
+# The simulator
+
+## It persists app settings and ignores your defaults
+
+Changing a default in `properties.xml` does **not** change what the simulator
+shows. It keeps the value it persisted the first time the app ran, so a property
+reads `false` while the XML plainly says `true`. This looks exactly like broken
+settings code and will send you debugging the wrong thing.
+
+Clear it: **File → Reset All App Data**. That also drops the loaded device, so
+relaunch the simulator and re-push afterwards.
+
+Diagnose before assuming a bug — print what the app actually sees:
+
+```monkeyc
+System.println("SETTINGS pro=" + _proMode + " ghost=" + _ghost);
+```
+
+If one property matches its XML default and another does not, you are looking at
+stale persistence, not a bug.
+
+## monkeydo wedges
+
+Regularly. Symptoms: exit 124, no output, or a hang with no push.
+
+```bash
+pkill -f monkeydo
+pkill -x simulator            # NOT `pkill -f simulator` -- see below
+"$SDK/bin/connectiq" &
+sleep 12
+"$SDK/bin/monkeydo" bin/app.prg fenix6pro
+```
+
+**Use `pkill -x simulator`, not `pkill -f simulator`.** The `-f` form matches the
+full command line of every process, and unrelated applications carry the word
+"simulator" in their arguments -- Claude Desktop's helper processes register a
+`claude-simulator` URL scheme, for instance. `pkill -f simulator` kills them too.
+`-x` matches the process name exactly.
+
+The simulator needs about 10-12 seconds before it will accept a push, and a
+further beat before its window is scriptable. Pushing too early gives a window
+titled "CIQ Simulator" with no device name and no display.
+
+For a watch face `monkeydo` does not exit on its own — it stays attached. That is
+normal; Ctrl-C once the face renders.
+
+## Screenshots
+
+Use `bin/ciq-capture`. If you must do it by hand, know the three failure modes:
+
+**1. `screencapture -R` grabs a screen region, not a window.** If the simulator is
+not in front you get a photograph of your terminal, saved successfully, with no
+error. Always raise the window and verify it came forward:
+
+```bash
+osascript -e 'tell application "System Events" to tell process "simulator" to set frontmost to true'
+sleep 2
+osascript -e 'tell application "System Events" to get name of first process whose frontmost is true'
+```
+
+**2. The window moves between restarts.** Read its bounds every time:
+
+```bash
+osascript -e 'tell application "System Events" to tell process "simulator" to get {position, size} of (first window whose name contains "CIQ Simulator")'
+```
+
+**3. The display is a sub-rectangle of the window.** Do not guess it. Render a
+full-screen marker colour, capture, and take its bounding box — that is the
+display rect exactly. `bin/ciq-calibrate` automates this. On a 2x Retina Mac with
+the fenix 6 Pro skin the answer is 518x518 at (155,345), a clean 2:1 for the
+260x260 display.
+
+Sanity check the result before believing it. A watch face is neither a blank
+white page nor solid black; if the dark fraction is outside roughly 25-90%, you
+captured the wrong window.
+
+**Mask round displays.** The square capture picks up a few pixels of the
+simulator's bezel skin in its corners, which do not exist on the device. Mask at
+4x and downsample or the edge stair-steps.
+
+The simulator's own **File → Save Screen Capture** works too, but its save dialog
+is a Java panel that does not respond to `Cmd+Shift+G` or normal AppleScript UI
+scripting. Fine by hand, not automatable.
+
+## Menus worth knowing (AppleScript-drivable)
+
+```bash
+osascript -e 'tell application "System Events" to tell process "simulator" to get name of every menu item of menu 1 of menu bar item "File" of menu bar 1'
+```
+
+| Menu | Item | Use |
+| --- | --- | --- |
+| File | Save Screen Capture | manual screenshot |
+| File | Reset All App Data | clear persisted settings |
+| File | Kill App | stop without closing |
+| Settings | Set Battery Status | test battery thresholds |
+| Settings | Set User Profile | resting HR and similar |
+| Settings | Trigger App Settings | fire `onSettingsChanged` |
+| Simulation | Activity Data | non-zero steps/calories |
+| Simulation | Time Simulation | check other times of day |
+
+The simulator reports zero steps and calories by default, because it has no
+activity data — not because your render path is broken. Use Simulation →
+Activity Data before concluding anything.
+
+## Sensor data
+
+`Toybox.SensorHistory` returns iterators whose most recent buckets are often
+`null`. Take the newest **non-null** sample rather than the newest sample:
+
+```monkeyc
+const SCAN_DEPTH = 24;
+
+function bodyBattery() as Number? {
+    if (!(Toybox has :SensorHistory)
+        || !(Toybox.SensorHistory has :getBodyBatteryHistory)) {
+        return null;
+    }
+    var it = Toybox.SensorHistory.getBodyBatteryHistory(
+        {:period => SCAN_DEPTH, :order => SensorHistory.ORDER_NEWEST_FIRST});
+    if (it == null) { return null; }
+    var sample = it.next();
+    var seen = 0;
+    while (sample != null && seen < SCAN_DEPTH) {
+        if (sample.data != null) { return sample.data.toNumber(); }
+        sample = it.next();
+        seen += 1;
+    }
+    return null;
+}
+```
+
+Always guard with `Toybox has :SensorHistory` — not every device has it, and the
+face must degrade to `--` rather than crash.
+
+## Verifying on real hardware
+
+The simulator renders on a backlit LCD and flatters everything. Colour, contrast
+and legibility decisions are not verified until seen on the device in daylight.
+Deploy over USB:
+
+```bash
+make build
+cp bin/app.prg /Volumes/GARMIN/GARMIN/APPS/
+# eject, then pick the face on-device
+```

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/references/store.md

@@ -0,0 +1,151 @@
+# Publishing
+
+**Portal:** <https://apps.garmin.com/developer/dashboard>
+**Guidelines:** <https://developer.garmin.com/connect-iq/app-review-guidelines/>
+
+Upload is a single file: the `.iq` from `make package`. It is a multi-device
+bundle — every declared product is inside it. Nothing else to attach.
+
+## App settings live on the phone, not the watch
+
+Connect IQ watch face settings are **not reachable from the watch**. The
+on-device face menu offers only Apply. Users configure via:
+
+Garmin Connect app → device → Connect IQ Apps → Watch Faces → *your face* → gear.
+
+Say this in the listing or it reads as a missing feature.
+
+Wiring, three files plus a handler:
+
+```xml
+<!-- resources/settings/properties.xml -->
+<properties>
+    <property id="proMode" type="boolean">false</property>
+</properties>
+
+<!-- resources/settings/settings.xml -->
+<settings>
+    <setting propertyKey="@Properties.proMode" title="@Strings.SettingProMode">
+        <settingConfig type="boolean" />
+    </setting>
+</settings>
+```
+
+```monkeyc
+// getValue THROWS when a key is absent -- which happens on a fresh install
+// before the Connect app has ever written settings. Default every read.
+private function boolSetting(key as String, fallback as Boolean) as Boolean {
+    try {
+        var value = Application.Properties.getValue(key);
+        if (value instanceof Lang.Boolean) { return value as Boolean; }
+    } catch (e) {
+        return fallback;
+    }
+    return fallback;
+}
+```
+
+```monkeyc
+// In the AppBase subclass -- without this the face keeps its old settings
+// until it is reselected.
+function onSettingsChanged() as Void {
+    WatchUi.requestUpdate();
+}
+```
+
+Re-read settings in both `onLayout` and `onShow`.
+
+See `reference/simulator.md` for why the simulator will lie to you about this.
+
+## Intellectual property
+
+Section 3(a) is stricter than people expect and explicitly covers your **listing
+text and images**, not just code:
+
+> You may not infringe any copyright, trademark, patent, trade secret, or any
+> other form of intellectual property. You must own or have a license to use all
+> IP included in or used by your app. This includes your app's software and
+> content, your developer account name, as well as the logos, images, and content
+> that you use to promote your app in the Connect IQ store.
+
+> Be careful using brand names and logos ... Be careful before making any mention
+> of a brand or using any logo or name that is not yours.
+
+And Garmin will not adjudicate:
+
+> It is not for us to decide whether your use of a third party's IP may be
+> infringing, properly used under a license, or fair use.
+
+So there is no approval to win. They accept it, and §5(b) lets them suspend with
+**no notice** if a rights holder complains — against the account, which carries
+your other apps too.
+
+Practical tiers for an homage:
+
+- **Highest risk:** a film title or real brand in the app name, launcher icon, or
+  screenshots. That is trademark use for product identity.
+- **Lower risk:** one factual, referential sentence in the description body.
+- **No risk, and usually better copy:** describe the *object* and the *era*. The
+  people who will recognise it recognise the shape, not the name.
+
+"The brand is dead so I can use it" does not hold. Abandonment is a legal finding
+requiring genuine non-use with no intent to resume, and it is moot if anyone holds
+a live registration — renewal is cheap and dormant heritage marks are routinely
+warehoused and revived. Check the registers before relying on it: USPTO Trademark
+Search, EUIPO eSearch, WIPO Global Brand Database, and the national register of
+the owner's country. A lapsed mark you do not own is still not a mark you *own*,
+which is what §3(a) asks for.
+
+Not legal advice. When it matters, ask a lawyer, not the store.
+
+## Donation links
+
+Permitted, with care. §1(a) prohibits listings that are advertising-focused or
+"serve primarily to drive affiliate traffic to a website", and §4(d) requires
+stating whether payment is needed. A single support line **after** a complete
+description, prefixed with *free*, clears both. Leading with it, or repeating it
+in the short description, does not.
+
+## Screenshots
+
+Regenerate from the build you are uploading, not an older one. Stale screenshots
+are the most common thing to forget after a redesign, and they misrepresent the
+version under review.
+
+```bash
+make build && make sim
+bin/ciq-capture docs/store/screenshot.png --face --size 260 --mask
+```
+
+Generate the launcher icon and any hero image from the same geometry the face
+uses, in a checked-in script, so they cannot drift from what the device renders.
+Two things that bite when reusing face-drawing code for artwork:
+
+- **Polarity must invert with the surface.** Face colours drawn on a hero's dark
+  background paint dark-on-dark and vanish. Take colours as parameters.
+- **Detail that sells at full size destroys legibility at icon size.** Ghost
+  segments turn every digit into an `8` at 40px. Drop them there.
+
+## Checklist
+
+- [ ] `make test` passes — and the tests actually compile (`reference/testing.md`)
+- [ ] `make lint` clean at level 3
+- [ ] `make package` builds every declared device
+- [ ] Developer key not committed
+- [ ] Screenshots regenerated from this build
+- [ ] Launcher icon is yours, at the size each device wants
+- [ ] Listing states that settings are in the Garmin Connect app
+- [ ] No third-party marks in name, icon, screenshots, or copy
+- [ ] Verified on real hardware in daylight, not just the simulator
+
+## Key hygiene
+
+The developer key signs your app id. Lose it and you cannot update the listing;
+commit it and anyone can impersonate your app.
+
+```bash
+make key    # generates ~/.Garmin/ConnectIQ/developer_key.der
+```
+
+Back it up somewhere private. Keep `bin/` and the key out of git, and run a
+pre-commit check that greps for `.der`/`.pem` in the index.

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/references/testing.md

@@ -0,0 +1,154 @@
+# Testing
+
+## The trap: a green run with zero tests compiled
+
+`monkey.jungle` almost always contains:
+
+```
+base.excludeAnnotations = test
+```
+
+That is correct — test code must not ship in the store build. But it strips
+`(:test)` from **every** target, including `--unit-test`. The result:
+
+```
+BUILD SUCCESSFUL
+Ran 0 tests
+```
+
+or, worse, a green run reported against stale test files that reference deleted
+symbols. Tests written months ago may never have executed once.
+
+**Fix** — a second jungle, passed as an additional `-f`:
+
+```
+# monkey.test.jungle
+# Loaded only for `make test`, after monkey.jungle, so (:test) code actually
+# compiles. The grammar requires a value here, so this is a placeholder that
+# matches no annotation.
+base.excludeAnnotations = none
+```
+
+```makefile
+TEST_JUNGLE := monkey.jungle;monkey.test.jungle
+
+test:
+	$(MONKEYC) -f "$(TEST_JUNGLE)" -d $(DEVICE) -o $(APP) -y $(KEY) -w -l 2 --unit-test
+	$(MONKEYDO) $(APP) $(DEVICE) -t
+```
+
+Note `base.excludeAnnotations =` with an empty value is a **syntax error**. Use a
+placeholder like `none`.
+
+**Prove your tests compile.** Do not take a green run on trust:
+
+```monkeyc
+(:test)
+function someExistingTest(logger as Logger) as Boolean {
+    return ThisDoesNotExist.definitelyNotAFunction();   // must FAIL the build
+}
+```
+
+If the build still succeeds, nothing is being compiled. Run this check whenever
+you inherit a project or change the jungle.
+
+## What is worth testing
+
+Monkey C unit tests run on-device or in the simulator and can only assert on pure
+logic — you cannot inspect rendered pixels. So test the two things that are pure:
+**geometry** and **formatting**. Keep `Dc` out of `Layout` and `Fields` and they
+stay testable.
+
+### Geometry invariants
+
+```monkeyc
+(:test)
+function goalBarClearsBothTextColumns(logger as Logger) as Boolean {
+    var barEnd = Layout.BAR_X + Layout.BAR_W;
+    return (Layout.BAR_X - Layout.LABEL_X) >= 40
+        && (Layout.VALUE_X - barEnd) >= 40;
+}
+```
+
+### Sweeps, not single values
+
+The single most valuable pattern here. A point test passes with the font height
+you assumed; the sweep catches the device you have not tried:
+
+```monkeyc
+(:test)
+function footerStaysOnScreenForAnyPlausibleFont(logger as Logger) as Boolean {
+    for (var labelH = 14; labelH <= 40; labelH += 1) {
+        for (var timeH = 40; timeH <= 120; timeH += 4) {
+            if (footerBottom(labelH, timeH / 2, timeH) >= Layout.SCREEN) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+```
+
+### Lookup tables where a typo is plausible
+
+A mistyped segment mask produces a *plausible* wrong digit — a `6` missing its
+top bar still reads as a `6` to a careless eye. Pin by count plus the specific
+features that distinguish neighbours:
+
+```monkeyc
+(:test)
+function everyDigitLightsTheRightNumberOfSegments(logger as Logger) as Boolean {
+    var expected = [6, 2, 5, 5, 4, 5, 6, 3, 7, 6];
+    for (var d = 0; d <= 9; d += 1) {
+        var count = 0;
+        for (var bit = 0; bit < 7; bit += 1) {
+            if ((Seg7.maskFor(d) & (1 << bit)) != 0) { count += 1; }
+        }
+        if (count != expected[d]) { return false; }
+    }
+    return true;
+}
+
+(:test)
+function zeroHasNoMiddleBarButEightDoes(logger as Logger) as Boolean {
+    return !Seg7.isLit(Seg7.maskFor(0), Seg7.SEG_G)
+        && Seg7.isLit(Seg7.maskFor(8), Seg7.SEG_G);
+}
+```
+
+### Thresholds, with the reasoning in the test name
+
+```monkeyc
+// A 14-day watch at 50% has a week left. Treating that as a warning was the bug.
+(:test)
+function halfChargeIsHealthyNotCaution(logger as Logger) as Boolean {
+    return Fields.batteryColor(50.0) == Palette.LABEL;
+}
+```
+
+### Dead code
+
+If a function is tested but never called, the tests pass and the feature does not
+exist. Grep for call sites of anything you have just written a test for.
+
+## What tests cannot catch
+
+Everything visual. Overlapping rows, a bar through a label, a face that is too
+dim, content drawn off-screen — all of it passes a green suite. **Capture a
+screenshot and look at it before committing.** Every visual bug in this skill's
+history was found by looking.
+
+```bash
+make build && make sim
+bin/ciq-capture /tmp/face.png --face --size 260
+# then Read the PNG
+```
+
+## Running
+
+```bash
+make test          # compile with the test jungle and run
+```
+
+`monkeydo ... -t` prints per-test PASS/FAIL and a summary. It also wedges often;
+see `reference/simulator.md`.

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/scripts/ciq-calibrate

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""Find where the device display sits inside the simulator window.
+
+Guessing this crops in bezel skin or clips the face. Instead: build a throwaway
+app that floods the whole screen with one unmistakable colour, push it, capture,
+and take the bounding box of that colour. That box IS the display rect, to the
+pixel, for whatever device skin is loaded.
+
+    ciq-calibrate                 # uses the fenix6pro device by default
+    ciq-calibrate --device fr955
+
+Writes ~/.cache/ciq-capture/calibration.json, which ciq-capture then uses.
+Re-run when switching to a device whose skin is a different size.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+CACHE = Path.home() / ".cache" / "ciq-capture"
+CIQ = Path.home() / "Library/Application Support/Garmin/ConnectIQ"
+HERE = Path(__file__).resolve().parent
+
+MARKER_RGB = (0xFF, 0x00, 0xFF)
+
+APP = """import Toybox.Application;
+import Toybox.Graphics;
+import Toybox.Lang;
+import Toybox.WatchUi;
+
+class CalApp extends Application.AppBase {
+    function initialize() { AppBase.initialize(); }
+    function getInitialView() as [WatchUi.Views] or [WatchUi.Views, WatchUi.InputDelegates] {
+        return [new CalView()];
+    }
+}
+
+class CalView extends WatchUi.WatchFace {
+    function initialize() { WatchFace.initialize(); }
+    function onUpdate(dc as Dc) as Void {
+        dc.setColor(0xFF00FF, 0xFF00FF);
+        dc.clear();
+    }
+}
+"""
+
+MANIFEST = """<?xml version="1.0" encoding="UTF-8"?>
+<iq:manifest xmlns:iq="http://www.garmin.com/xml/connectiq" version="3">
+    <iq:application entry="CalApp" id="{appid}" launcherIcon="@Drawables.LauncherIcon"
+        minApiLevel="3.1.0" name="@Strings.AppName" type="watchface">
+        <iq:products><iq:product id="{device}"/></iq:products>
+        <iq:permissions/>
+        <iq:languages><iq:language>eng</iq:language></iq:languages>
+        <iq:barrels/>
+    </iq:application>
+</iq:manifest>
+"""
+
+JUNGLE = "project.manifest = manifest.xml\nbase.sourcePath = source\nbase.resourcePath = resources\n"
+STRINGS = '<?xml version="1.0" encoding="UTF-8"?>\n<strings><string id="AppName">cal</string></strings>\n'
+DRAWABLES = ('<?xml version="1.0" encoding="UTF-8"?>\n<drawables>'
+             '<bitmap id="LauncherIcon" filename="icon.png"/></drawables>\n')
+
+
+def sdk_bin():
+    cfg = CIQ / "current-sdk.cfg"
+    if not cfg.is_file():
+        sys.exit("No SDK selected. Open SdkManager.app and install/select an SDK.")
+    return Path(cfg.read_text().strip()) / "bin"
+
+
+def osa(script):
+    r = subprocess.run(["osascript", "-e", script], capture_output=True, text=True)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--device", default="fenix6pro")
+    ap.add_argument("--key", default=str(Path.home() / ".Garmin/ConnectIQ/developer_key.der"))
+    args = ap.parse_args()
+
+    try:
+        from PIL import Image
+    except ImportError:
+        sys.exit("Needs Pillow: pip install pillow")
+
+    key = Path(args.key)
+    if not key.is_file():
+        sys.exit(f"No developer key at {key}. Generate one with `make key`.")
+
+    sdk = sdk_bin()
+    import uuid
+
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        (root / "source").mkdir()
+        (root / "resources/drawables").mkdir(parents=True)
+        (root / "resources/strings").mkdir(parents=True)
+
+        (root / "source/CalApp.mc").write_text(APP)
+        (root / "manifest.xml").write_text(
+            MANIFEST.format(appid=uuid.uuid4().hex, device=args.device))
+        (root / "monkey.jungle").write_text(JUNGLE)
+        (root / "resources/strings/strings.xml").write_text(STRINGS)
+        (root / "resources/drawables/drawables.xml").write_text(DRAWABLES)
+        Image.new("RGB", (40, 40), (0, 0, 0)).save(root / "resources/drawables/icon.png")
+
+        prg = root / "cal.prg"
+        print(f"building marker app for {args.device} ...")
+        r = subprocess.run(
+            [str(sdk / "monkeyc"), "-f", str(root / "monkey.jungle"),
+             "-d", args.device, "-o", str(prg), "-y", str(key), "-w"],
+            capture_output=True, text=True, cwd=root)
+        if "BUILD SUCCESSFUL" not in (r.stdout + r.stderr):
+            sys.exit("marker build failed:\n" + r.stdout + r.stderr)
+
+        subprocess.run(["pkill", "-f", "monkeydo"], capture_output=True)
+        subprocess.Popen([str(sdk / "connectiq")],
+                         stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        time.sleep(10)
+        subprocess.Popen([str(sdk / "monkeydo"), str(prg), args.device],
+                         stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        print("pushing to simulator ...")
+        time.sleep(20)
+
+        osa('tell application "System Events" to tell process "simulator" '
+            "to set frontmost to true")
+        time.sleep(2)
+
+        out = osa('tell application "System Events" to tell process "simulator" to get '
+                  '{position, size} of (first window whose name contains "CIQ Simulator")')
+        parts = [p.strip() for p in out.split(",") if p.strip()]
+        if len(parts) != 4:
+            sys.exit("could not read the simulator window bounds")
+        x, y, w, h = (int(p) for p in parts)
+
+        shot = root / "cal.png"
+        subprocess.run(["screencapture", "-x", f"-R{x},{y},{w},{h}", str(shot)], check=True)
+
+        im = Image.open(shot).convert("RGB")
+        px = im.load()
+        xs, ys = [], []
+        for yy in range(im.height):
+            for xx in range(im.width):
+                r_, g_, b_ = px[xx, yy]
+                if r_ > 200 and b_ > 200 and g_ < 60:
+                    xs.append(xx)
+                    ys.append(yy)
+
+        if not xs:
+            sys.exit(
+                "marker not found in the capture.\n"
+                "The simulator was probably not in front, or the app did not load."
+            )
+
+        left, top = min(xs), min(ys)
+        width, height = max(xs) - left + 1, max(ys) - top + 1
+        if abs(width - height) > 2:
+            print(f"warning: marker is {width}x{height}, not square -- "
+                  "non-square display or a partial capture", file=sys.stderr)
+
+        scale = round(width / max(im.width and 1, 1)) or 1
+        rect = {"left": left, "top": top, "size": max(width, height),
+                "scale": 2 if width > 300 else 1, "device": args.device}
+
+        CACHE.mkdir(parents=True, exist_ok=True)
+        CALIB = CACHE / "calibration.json"
+        CALIB.write_text(json.dumps(rect, indent=2) + "\n")
+        print(f"\ndisplay rect: {width}x{height} at ({left},{top}) in a "
+              f"{im.width}x{im.height} capture")
+        print(f"written to {CALIB}")
+
+
+if __name__ == "__main__":
+    main()