@olegkoval/agent-skills 1.28.0 → 1.30.0

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

@@ -222,3 +222,31 @@ digit nought" — they are different pictures.
   checked against a boundary: a stroke straddles its path, putting half its width
   outside what you verified.
 - Order matters when compositing. Pasting a square image over a ring erases it.
+
+## Fonts are tiers, not pixel heights
+
+`FONT_XTINY` is not a size — it is a request, and the device answers with a
+glyph proportionate to its own screen. A 454px watch supplies a materially
+taller `FONT_XTINY` than a 260px one, unasked.
+
+So when text looks wrong at a new resolution, **the bug is a length that failed
+to scale, never the font**. Do not branch on screen size to pick a bigger tier:
+that double-scales, and labels end up wider than the containers naming them.
+Tried on a real face, `FONT_SMALL` on a 1.75x screen made a four-character
+subdial label wider than the arc it sat inside; plain `FONT_XTINY` was correct
+on sight.
+
+The cheap check before theorising: does a sibling face that never touched its
+fonts render correctly at the new size? If yes, fonts are not your problem.
+
+**Where a font tier IS a real constraint, the limit is the container.** A label
+inside a 30-unit arc has to fit that arc at every resolution, which is a
+different question from how it scales. Derive placement from the MEASURED glyph:
+
+```monkeyc
+var h = dc.getFontHeight(Fonts.label());
+var y = cy + DIGIT_TOP_DY - Layout.grid(2) - h;   // seat it on its own height
+```
+
+A fixed offset scales with the screen while the glyph does not, which puts the
+label on top of its own digits at one size and adrift at another.

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

@@ -1,9 +1,9 @@
 # Publishing through the browser
 
-`references/store.md` covers *what* the listing needs. This covers *driving the
+`reference/store.md` covers *what* the listing needs. This covers *driving the
 portal*, which is the only way in — Garmin publishes no submission API.
 
-Run `scripts/ciq-release` before opening a browser. Everything it checks is
+Run `bin/ciq-release` before opening a browser. Everything it checks is
 something you would otherwise discover halfway through the form.
 
 ## The portal is automatable
@@ -44,6 +44,113 @@ Three separate traps in that block:
 Verify by checking the URL after `goto`: an unauthenticated session is bounced
 to `sso.garmin.com/portal/sso/...`, an authenticated one stays put.
 
+### When cookie import fails, `browse connect` is the answer
+
+Cookie import is the fast path and it fails in two common ways, both of which
+look identical from the outside (`Imported 0 cookies`):
+
+- **The browser encrypts its cookie store** and browse cannot decrypt it. Comet
+  is one. Reading the key out of the macOS keychain yourself is credential
+  extraction, an agent permission-classifier will block it, and it should.
+- **You are signed into a different browser than you think.** Check the cookie
+  DB's mtime rather than guessing — the store of the browser you just used is
+  written seconds ago:
+
+```bash
+for n in "Google/Chrome/Default" "Comet/Default" "BraveSoftware/Brave-Browser/Default"; do
+  f="$HOME/Library/Application Support/$n/Cookies"
+  [ -f "$f" ] && echo "$n $(stat -f '%Sm' -t '%H:%M:%S' "$f")"
+done
+```
+
+The path that works regardless is to put the login **inside the browser browse
+drives**:
+
+```bash
+$B connect                    # headed Chromium under browse's control
+$B goto https://apps.garmin.com/en-US/developer/dashboard
+$B focus                      # then the human signs in, in that window
+```
+
+No import, no keychain, no profile mismatch. `handoff` is NOT equivalent — it
+opens a *separate* browser whose session `resume` does not inherit.
+
+**Do not trust window counts from System Events.** `count of windows` returns 0
+for Chromium browsers without macOS automation permission, even while the window
+is plainly on screen — Finder returns a real number, so the API looks like it is
+working. Diagnosing "the browser never opened" from that reading sends you off
+fixing the wrong thing.
+
+### Protect the daemon session
+
+Every browse daemon restart destroys the authenticated context and you start
+over. Restarts are triggered by crashes and by some error paths, and the giveaway
+is `[browse] Starting server...` in otherwise-unrelated output. Check
+`$B url` after any surprise: `about:blank` means the context is gone.
+
+Practical consequence: between the human signing in and the work being finished,
+run as few commands as possible, and none that can throw.
+
+### Uploads are path-restricted
+
+`$B upload` refuses any file outside `/private/tmp` or the current repo:
+
+```
+Path must be within: /private/tmp, /Users/.../some-other-repo
+```
+
+Note it validates against the shell's *current* directory, which may be a
+different project than the one you are publishing. Copy the package first:
+
+```bash
+cp bin/<name>.iq /private/tmp/ && $B upload "input[type=file]" /private/tmp/<name>.iq
+```
+
+### Developer URLs, and the two forms
+
+The dashboard's app links go to the PUBLIC page (`/apps/<appId>`), not the
+editor. The developer routes are:
+
+```
+https://apps.garmin.com/developer/<devId>/apps/<appId>/update   # new version
+https://apps.garmin.com/developer/<devId>/apps/<appId>/edit     # listing text
+```
+
+`<devId>` is stable across your apps — read it off any editor URL once. Guessing
+`/developer/<appId>/edit` returns 404.
+
+Field handles, current as of mid-2026:
+
+| What | Selector |
+| --- | --- |
+| Package | `input[type=file]` |
+| Version string | third `input[type=text]` on `/update` |
+| Description | `textarea[name="app-desc-en"]` |
+| What's New | `textarea[name="app-whats-new-en"]` |
+
+React controls these, so assigning `.value` alone does not register. Use the
+native setter and dispatch both events:
+
+```js
+var set = Object.getOwnPropertyDescriptor(
+  window.HTMLTextAreaElement.prototype, 'value').set;
+set.call(el, text);
+el.dispatchEvent(new Event('input',  { bubbles: true }));
+el.dispatchEvent(new Event('change', { bubbles: true }));
+```
+
+Pass long copy through a staged `<script type="application/json">` node rather
+than interpolating it into a `js` one-liner — multi-line store copy will not
+survive shell and JS quoting intact.
+
+### The public page lags the portal
+
+After a successful publish the portal reports `Status: Verified, Signature:
+Verified` and expands the product list immediately. The **public** app page can
+still show the previous device list minutes later. The portal is authoritative;
+do not re-upload because the public page has not caught up, and do not report
+the new devices as live until it has.
+
 ## "The Connect IQ store is currently in maintenance mode"
 
 This string is in the DOM of the dashboard and of every app page, next to
@@ -68,8 +175,8 @@ the next one.
 
 ```bash
 $B upload "input[type=file]" "$(pwd)/bin/<name>.iq"
-$B fill "input[id*='version'],input[name*='version']" "2.0"
-$B click "button:has-text('Upload and publish')"
+$B fill @e43 "2.0"
+$B click @e46                      # "Upload and publish"
 ```
 
 On success the page reports **Status: Verified, Signature: Verified** and
@@ -84,6 +191,28 @@ The description arrives pre-filled with the copy from the PREVIOUS version.
 After a redesign it describes a face that no longer exists, and nothing prompts
 you about it. Re-paste from `docs/store/listing.md` every time.
 
+### Step 2 can fail silently — verify the live page
+
+Observed on a real submission: the package uploaded, the version went live, and
+*Submit* on step 2 **saved nothing**. No error, no validation message; the page
+simply stayed on `/update` instead of redirecting. The listing kept the previous
+description for as long as nobody looked.
+
+Treat uploading a version and updating its listing as two independent
+operations, whatever the form implies:
+
+1. After *Submit*, check that the URL actually changed to `/apps/<uuid>`.
+   Sitting on `/update` is the failure signature.
+2. Re-fetch the **public** page and string-match something distinctive from the
+   new copy. This is the only real confirmation.
+3. If it did not save, go back and use the separate **Edit Details** flow, which
+   does work.
+
+A long description may also be truncated behind a read-more on the public page,
+so a missing string near the *end* of the copy is not automatically a failed
+save — check a distinctive phrase from early in the text too before concluding
+either way.
+
 ## Image slots, in DOM order
 
 There are seven `input[type=file]` elements and none of them carry a name, id
@@ -115,7 +244,7 @@ Submit:
   same symbol space.
 
 Write settings paths in words: *"Garmin Connect app, then: your device, Connect
-IQ Apps, Watch Faces, the app name, settings"*. `scripts/ciq-release` checks the fenced
+IQ Apps, Watch Faces, <app>, settings"*. `bin/ciq-release` checks the fenced
 blocks of `listing.md` for both classes before you open a browser.
 
 The error text renders as a leaf node with no `aria-invalid` anywhere, so find

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

@@ -26,11 +26,30 @@ 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
+open -a "$SDK/bin/ConnectIQ.app"   # NOT "$SDK/bin/connectiq" -- see below
+sleep 15
 "$SDK/bin/monkeydo" bin/app.prg fenix6pro
 ```
 
+**Launch the `.app` bundle, not the `bin/connectiq` shell script.** Started via
+the script from a non-interactive context, the simulator runs as a GUI process
+that never creates a window:
+
+```
+count of windows -> 0
+```
+
+Every capture then fails with "simulator did not come forward", which reads
+exactly like the frontmost-check being broken and sends you off calibrating
+something that was never wrong. `open -a "$SDK/bin/ConnectIQ.app"` opens a real
+window and everything downstream works. Confirm before pushing:
+
+```bash
+osascript -e 'tell application "System Events" to tell process "simulator" \
+  to get {count of windows, name of window 1}'
+# -> 1, CIQ Simulator - Forerunner® 970 (6.0.2)
+```
+
 **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
@@ -96,6 +115,7 @@ osascript -e 'tell application "System Events" to tell process "simulator" to ge
 | Settings | Set Battery Status | test battery thresholds |
 | Settings | Set User Profile | resting HR and similar |
 | Settings | Trigger App Settings | fire `onSettingsChanged` |
+| Settings | Display Mode → Always-Active | **the AMOLED always-on frame** |
 | Simulation | Activity Data | non-zero steps/calories |
 | Simulation | Time Simulation | check other times of day |
 
@@ -103,6 +123,70 @@ 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.
 
+**Settings → Display Mode → Always-Active is how you see the always-on frame**,
+and it is a submenu, not a checkbox. The two items are *High Power* and
+*Always-Active* — NOT "Normal" and "Always-On", which is what the naming
+everywhere else in the SDK leads you to type. Enumerate rather than guess:
+
+```bash
+osascript -e 'tell application "System Events" to tell process "simulator" \
+  to get name of menu items of menu 1 of menu item "Display Mode" \
+  of menu 1 of menu bar item "Settings" of menu bar 1'
+```
+
+Settings → *Sleep Mode* is a different thing
+entirely — the user's sleep window, not the watch-face power state — and
+clicking it leaves the face fully lit, which looks like `onEnterSleep` never
+firing:
+
+```bash
+osascript -e 'tell application "System Events" to tell process "simulator" \
+  to click menu item "Always-Active" of menu 1 of menu item "Display Mode" \
+  of menu 1 of menu bar item "Settings" of menu bar 1'
+```
+
+Check both directions. Switching an AMOLED product to Always-On should give the
+restricted frame; switching a MIP product to Always-On should change **nothing**,
+because it carries no `requiresBurnInProtection` and has no reason to dim.
+
+Measure rather than eyeball the result — the budget is a number:
+
+```python
+# lit fraction and centroid inside the round glass, from a raw capture
+lit = sum(1 for p in glass_pixels if max(p) > 40)
+print(100 * lit / len(glass_pixels))     # keep well under 10%
+```
+
+The centroid is the more useful of the two. It caught a blanked leading digit
+cell leaving the time 106px right of centre — invisible in a passing test suite,
+and easy to look straight past in a screenshot.
+
+### Stale monkeydo processes wedge the next run
+
+`make test` hanging forever, or `Unable to connect to simulator`, is usually an
+earlier `monkeydo` still holding the port rather than anything wrong with the
+build. They accumulate silently across a session — several were found alive
+here from runs an hour old.
+
+```bash
+pgrep -lf "monkeydo|bin/shell"      # look before blaming the test
+pkill -f monkeydo; pkill -f "bin/shell"
+```
+
+Kill the simulator too if it will not come forward, then relaunch with
+`open -a "$SDK/bin/ConnectIQ.app"` and re-push.
+
+### A locked Mac silently defeats every capture
+
+`screencapture` on a locked machine photographs the login screen, and the
+AppleScript menu clicks report success while going nowhere. The result is a
+plausible PNG containing a desktop wallpaper, and analysis of it produces
+confident nonsense — a lit-pixel fraction of 0.0005 rather than an error.
+
+Assert the capture contains a display before measuring it: the round glass is
+a large dark disc, so a near-zero dark fraction over any 454-square window
+means there is no watch in the frame.
+
 ## Sensor data
 
 `Toybox.SensorHistory` returns iterators whose most recent buckets are often

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

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""Pull design inspiration from open APIs and turn it into device-truthful
+design tokens.
+
+    ciq-inspire --brand garmin.com              # Brandfetch: colours, fonts
+    ciq-inspire --image ~/crest.png             # dominant colours from a file
+    ciq-inspire --prior-art "chronograph"       # GitHub: Monkey C faces to read
+    ciq-inspire --brand acme.com --json tokens.json
+
+Every colour that comes back is quantized to the 4x4x4 lattice and ranked by
+reflectance BEFORE you see it. A palette approved in its source form is a
+palette that changes the moment it reaches the watch, and the change is never
+small: an off-lattice mid-grey and an off-lattice pale grey routinely collapse
+onto the same value.
+
+Sources, and what each is actually good for
+-------------------------------------------
+
+  Brandfetch   https://brandfetch.com -- brand colours and typeface names for a
+               domain. Set BRANDFETCH_API_KEY. Free tier is enough.
+  GitHub       prior art: real Monkey C sources you can read for how a thing was
+               drawn. Uses `gh` when installed (higher rate limit), else
+               unauthenticated HTTP.
+  Local image  dominant colours from a logo, crest or reference photo. Needs
+               Pillow, which the screenshot tooling already requires.
+
+There is NO public Connect IQ Store API. Store research is manual.
+
+IP, and this is not optional
+----------------------------
+
+Brandfetch will happily hand you another company's colours, wordmark and logo.
+Colours and proportions are fine to be inspired by. Marks are not: the Connect
+IQ store rejects, and Garmin removes, faces carrying a third party's name or
+logo in the face, the icon, the screenshots or the copy. Use --brand for a
+domain you own, or for palette study only. See references/store.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+LEVELS = (0x00, 0x55, 0xAA, 0xFF)
+UA = "ciq-inspire (Connect IQ design tooling)"
+
+
+def quantize(rgb):
+    return tuple(min(LEVELS, key=lambda level: abs(level - c)) for c in rgb)
+
+
+def hexof(rgb):
+    return "#%02X%02X%02X" % rgb
+
+
+def luminance(rgb):
+    r, g, b = rgb
+    return (r * 299 + g * 587 + b * 114) // 1000
+
+
+def parse_hex(text):
+    t = (text or "").strip().lstrip("#")
+    if len(t) == 3:
+        t = "".join(c * 2 for c in t)
+    if len(t) != 6:
+        return None
+    try:
+        return tuple(int(t[i:i + 2], 16) for i in (0, 2, 4))
+    except ValueError:
+        return None
+
+
+def get(url, headers=None):
+    req = urllib.request.Request(url, headers={"User-Agent": UA, **(headers or {})})
+    try:
+        with urllib.request.urlopen(req, timeout=20) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            if not isinstance(data, dict):
+                print(f"API returned non-dict response", file=sys.stderr)
+                return None
+            return data
+    except json.JSONDecodeError as exc:
+        print(f"API returned invalid JSON: {exc}", file=sys.stderr)
+        return None
+
+
+# ------------------------------------------------------------- brandfetch ----
+
+def from_brandfetch(domain):
+    key = os.environ.get("BRANDFETCH_API_KEY")
+    if not key:
+        print("BRANDFETCH_API_KEY is not set. Get a free key at "
+              "https://developers.brandfetch.com and export it.", file=sys.stderr)
+        return None
+    url = f"https://api.brandfetch.io/v2/brands/{urllib.parse.quote(domain)}"
+    try:
+        data = get(url, {"Authorization": f"Bearer {key}"})
+    except urllib.error.HTTPError as exc:
+        print(f"Brandfetch {exc.code} for {domain}: {exc.reason}", file=sys.stderr)
+        return None
+    except urllib.error.URLError as exc:
+        print(f"Brandfetch unreachable: {exc.reason}", file=sys.stderr)
+        return None
+
+    if data is None:
+        return None
+
+    colours = []
+    for c in data.get("colors") or []:
+        rgb = parse_hex(c.get("hex"))
+        if rgb:
+            colours.append({"rgb": rgb, "role": c.get("type") or "unknown"})
+
+    fonts = [f.get("name") for f in (data.get("fonts") or []) if f.get("name")]
+    return {
+        "source": f"brandfetch:{domain}",
+        "name": data.get("name") or domain,
+        "colours": colours,
+        # Recorded for tone only. No system font on the watch is any of these,
+        # and a segment display has to be drawn rather than typeset.
+        "typefaces": fonts,
+    }
+
+
+# ------------------------------------------------------------------ image ----
+
+def from_image(path, count):
+    try:
+        from PIL import Image
+    except ImportError:
+        print("Pillow is required for --image: python3 -m pip install Pillow",
+              file=sys.stderr)
+        return None
+    if not Path(path).is_file():
+        print(f"No such file: {path}", file=sys.stderr)
+        return None
+
+    img = Image.open(path).convert("RGB")
+    img.thumbnail((160, 160))
+    # Quantize FIRST, then count. Counting true colours and quantizing after
+    # returns near-duplicates that collapse into one value on the panel and
+    # makes a two-colour logo look like a six-colour palette.
+    # Raw bytes rather than getdata(): getdata() is deprecated in Pillow 14 and
+    # tobytes() has meant the same thing in every version.
+    raw = img.tobytes()
+    tally = {}
+    for i in range(0, len(raw) - 2, 3):
+        q = quantize(raw[i:i + 3])
+        tally[q] = tally.get(q, 0) + 1
+    total = sum(tally.values())
+    if not tally or total == 0:
+        return {
+            "source": f"image:{Path(path).name}",
+            "name": Path(path).stem,
+            "colours": [],
+            "typefaces": [],
+        }
+    ranked = sorted(tally.items(), key=lambda kv: -kv[1])[:count]
+    return {
+        "source": f"image:{Path(path).name}",
+        "name": Path(path).stem,
+        "colours": [{"rgb": rgb, "role": f"{(n * 100) // total}% of pixels"}
+                    for rgb, n in ranked],
+        "typefaces": [],
+    }
+
+
+# ---------------------------------------------------------------- github ----
+
+def gh_search(query, limit):
+    """Repository search. `gh` first: unauthenticated search is rate-limited to
+    10/minute per IP and fails opaquely once you cross it."""
+    q = urllib.parse.quote(query)
+    path = f"search/repositories?q={q}&sort=stars&per_page={limit}"
+    if shutil.which("gh"):
+        try:
+            out = subprocess.run(["gh", "api", path], capture_output=True,
+                                 text=True, timeout=25)
+            if out.returncode == 0:
+                return json.loads(out.stdout)
+        except (subprocess.SubprocessError, json.JSONDecodeError):
+            pass
+    try:
+        return get(f"https://api.github.com/{path}")
+    except (urllib.error.HTTPError, urllib.error.URLError) as exc:
+        print(f"GitHub search failed: {exc}", file=sys.stderr)
+        return None
+
+
+def from_prior_art(theme, limit):
+    # GitHub's linguist knows Monkey C, and `language:"Monkey C"` is by far the
+    # highest-signal filter available -- ~2600 repositories, essentially all of
+    # them Connect IQ. Free-text terms are ANDed against name/description/readme
+    # on top of it, so anything specific ("chronograph") routinely returns zero.
+    # Fall back to the whole corpus rather than reporting nothing.
+    data = gh_search(f'{theme} language:"Monkey C"', limit)
+    if data and not data.get("items"):
+        print(f'No Monkey C repository mentions "{theme}"; showing the most-starred '
+              "Connect IQ projects instead.", file=sys.stderr)
+        data = gh_search('language:"Monkey C"', limit)
+    if not data:
+        return []
+    out = []
+    for repo in data.get("items", []):
+        out.append({
+            "repo": repo.get("full_name"),
+            "stars": repo.get("stargazers_count"),
+            "url": repo.get("html_url"),
+            "license": ((repo.get("license") or {}).get("spdx_id")) or "none",
+            "description": (repo.get("description") or "")[:110],
+        })
+    return out
+
+
+# ----------------------------------------------------------------- report ----
+
+def roles(colours):
+    """Suggest palette roles by reflectance, not by hue.
+
+    On a transflective panel brightness IS reflectance, so glance order is a
+    luminance ladder. Anything that assigns roles by hue produces a face where
+    the fastest-moving element is the dimmest thing on the dial."""
+    uniq = sorted({quantize(c["rgb"]) for c in colours}, key=luminance)
+    if not uniq:
+        return {}
+    darkest, brightest = uniq[0], uniq[-1]
+    mid = uniq[len(uniq) // 2]
+    # An accent must be bright enough to read AND distinguishable from the ink.
+    accent = max((c for c in uniq if c not in (darkest, brightest)),
+                 key=luminance, default=brightest)
+    return {
+        "DIAL": darkest,
+        "RULE": mid if mid not in (darkest, brightest) else darkest,
+        "INDEX": brightest,
+        "HAND": brightest,
+        "ACCENT": accent,
+    }
+
+
+def report(bundles, art):
+    for b in bundles:
+        print(f"\n{b['name']}  ({b['source']})")
+        print("-" * 62)
+        if not b["colours"]:
+            print("  no colours returned")
+        for c in sorted(b["colours"], key=lambda c: -luminance(quantize(c["rgb"]))):
+            src, q = tuple(c["rgb"]), quantize(c["rgb"])
+            shift = "" if src == q else f"  <- {hexof(src)} shifted"
+            print(f"  {hexof(q)}  lum {luminance(q):>3}  {c['role']}{shift}")
+        if b["typefaces"]:
+            print(f"  typefaces (tone only, none exist on device): "
+                  f"{', '.join(b['typefaces'])}")
+
+    merged = [c for b in bundles for c in b["colours"]]
+    if merged:
+        print("\nSuggested roles, ordered by reflectance")
+        print("-" * 62)
+        for role, rgb in roles(merged).items():
+            print(f"  {role:<8} {hexof(rgb)}  lum {luminance(rgb)}")
+        print("\n  Sanity-check before adopting: DIAL to INDEX should be the "
+              "biggest\n  luminance gap you have, and ACCENT must not be the "
+              "dimmest colour on\n  the face -- see references/display.md.")
+
+    if art:
+        print("\nPrior art on GitHub -- read the source, do not copy it")
+        print("-" * 62)
+        for r in art:
+            print(f"  {r['stars']:>5}*  {r['repo']}  [{r['license']}]")
+            if r["description"]:
+                print(f"         {r['description']}")
+        print("\n  Licences vary and most of these carry none, which means all "
+              "rights\n  reserved. Read for technique; write your own code.")
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--brand", metavar="DOMAIN", help="Brandfetch lookup")
+    ap.add_argument("--image", metavar="PATH", help="dominant colours from a file")
+    ap.add_argument("--colours", type=int, default=6, help="how many from --image")
+    ap.add_argument("--prior-art", metavar="THEME", help="search GitHub for faces")
+    ap.add_argument("--limit", type=int, default=8, help="prior-art results")
+    ap.add_argument("--json", metavar="PATH", help="also write tokens as JSON")
+    args = ap.parse_args()
+
+    if not (args.brand or args.image or args.prior_art):
+        ap.error("nothing to do: pass --brand, --image and/or --prior-art")
+
+    bundles = []
+    if args.brand:
+        b = from_brandfetch(args.brand)
+        if b:
+            bundles.append(b)
+    if args.image:
+        b = from_image(args.image, args.colours)
+        if b:
+            bundles.append(b)
+    art = from_prior_art(args.prior_art, args.limit) if args.prior_art else []
+
+    if not bundles and not art:
+        print("No sources returned anything usable.", file=sys.stderr)
+        return 1
+
+    report(bundles, art)
+
+    if args.json:
+        merged = [c for b in bundles for c in b["colours"]]
+        Path(args.json).write_text(json.dumps({
+            "sources": [b["source"] for b in bundles],
+            "palette": [hexof(quantize(c["rgb"])) for c in merged],
+            "roles": {k: hexof(v) for k, v in roles(merged).items()},
+            "priorArt": art,
+        }, indent=2) + "\n", encoding="utf-8")
+        print(f"\nWrote {args.json}")
+
+    print("\nNext: draw exactly three variants as SVG and run ciq-mock on them.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())