@olegkoval/agent-skills 1.28.0 → 1.30.0

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

@@ -1,11 +1,6 @@
 ---
 name: garmin-watchface
 description: Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C. Use when working on a Connect IQ watch face or app - creating one, fixing layout that clips or overlaps, capturing simulator screenshots, adding app settings, widening device support, or preparing a Connect IQ Store submission. Encodes the traps that silently produce a passing build and a broken face.
-license: MIT
-allowed-tools: Bash, Read, Write, Edit, Grep, Glob
-compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires macOS, the Connect IQ SDK, a JDK, and Python 3 (Pillow for screenshot cropping).
-metadata:
-  targets: [_source-only]
 ---
 <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
 
@@ -16,43 +11,43 @@ that draws off the bottom of the screen, a test suite that contains no tests, an
 a colour that is not the colour you get. Everything below is a failure mode that
 looked like success first.
 
-**Read `references/` files as needed — do not read them all up front.**
+**Read `reference/` files as needed — do not read them all up front.**
 
 | File | When |
 | --- | --- |
-| `references/display.md` | Choosing colours, anything about brightness or legibility |
-| `references/layout.md` | Positioning anything; content clipped, overlapping, or off-screen |
-| `references/testing.md` | Writing tests; a suspiciously clean test run |
-| `references/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
-| `references/devices.md` | Adding device support, launcher icons, API levels |
-| `references/store.md` | Publishing, listing copy, IP questions |
-| `references/publishing.md` | Driving the store portal in a browser; upload/update flow, validator rejections |
+| `reference/display.md` | Choosing colours, brightness, legibility; **AMOLED always-on and burn-in** |
+| `reference/layout.md` | Positioning anything; content clipped, overlapping, or off-screen |
+| `reference/testing.md` | Writing tests; a suspiciously clean test run |
+| `reference/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
+| `reference/devices.md` | Adding device support, launcher icons, API levels |
+| `reference/store.md` | Publishing, listing copy, IP questions |
+| `reference/publishing.md` | Driving the store portal in a browser; upload/update flow, validator rejections |
 
 ## Tools
 
 Run these rather than reinventing them. All are standalone.
 
 ```bash
-<skill-dir>/scripts/ciq-doctor                    # toolchain check: SDK, JDK, key, devices
-<skill-dir>/scripts/ciq-devices                   # survey installed devices by resolution
-<skill-dir>/scripts/ciq-devices --same-as fenix6pro   # products you can add with no code change
-<skill-dir>/scripts/ciq-capture out.png           # calibrated simulator screenshot
-<skill-dir>/scripts/ciq-capture out.png --face --size 260   # cropped + masked to the round display
-<skill-dir>/scripts/ciq-calibrate                 # re-derive the display rect if capture looks wrong
-<skill-dir>/scripts/ciq-release       # pre-submission check: package, screenshots, icon, keys, copy
+bin/ciq-doctor                    # toolchain check: SDK, JDK, key, devices
+bin/ciq-devices                   # survey installed devices by resolution
+bin/ciq-devices --same-as fenix6pro   # products you can add with no code change
+bin/ciq-capture out.png           # calibrated simulator screenshot
+bin/ciq-capture out.png --face --size 260   # cropped + masked to the round display
+bin/ciq-calibrate                 # re-derive the display rect if capture looks wrong
+bin/ciq-release                   # pre-submission check: package, screenshots, icon, keys, copy
 ```
 
-`<skill-dir>/scripts/ciq-release` is what you run before opening the store
-portal. Every check in it is something otherwise discovered halfway through the
-submission form -- a stale screenshot set, an icon still copied from the last
-project, or copy containing a character the description validator rejects.
+`bin/ciq-release` is what you run before opening the store portal. Every check
+in it is something otherwise discovered halfway through the submission form --
+a stale screenshot set, an icon still copied from the last project, or copy
+containing a character the description validator rejects.
 
-`<skill-dir>/scripts/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
+`bin/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
 a window: without a frontmost check it silently photographs whatever is on top,
 and the window moves between simulator restarts. Both failure modes produce a
 plausible PNG of the wrong thing.
 
-## The five things that will bite you
+## The seven things that will bite you
 
 ### 1. `make test` can compile zero tests and report success
 
@@ -62,7 +57,7 @@ get `BUILD SUCCESSFUL` and a green run with nothing compiled — even when the t
 files reference symbols that no longer exist.
 
 Fix: a second jungle passed as an additional `-f`. See
-`<skill-dir>/templates/monkey.test.jungle` and the `test` target in `<skill-dir>/templates/Makefile`.
+`templates/monkey.test.jungle` and the `test` target in `templates/Makefile`.
 
 **Prove it before you trust it.** Put a deliberately unresolvable symbol in one
 test and confirm the build fails:
@@ -83,6 +78,13 @@ they look. Measured on fenix 6 Pro:
 | `FONT_SMALL` | 32 |
 | `FONT_NUMBER_MEDIUM` | 74 |
 
+**Font tiers already scale with the device.** `FONT_XTINY` is a tier, not a
+pixel height: a 454px watch supplies a proportionately taller glyph 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 add screen-size branching
+to pick a bigger tier -- doing so double-scales, and labels end up wider than
+the containers naming them.
+
 Content drawn past the screen height is simply invisible — no error, no warning,
 no clipping indicator. A two-line `FONT_NUMBER_MEDIUM` block is 148px of a 260px
 face.
@@ -97,7 +99,7 @@ function clampRuleY(derived as Number, footerH as Number) as Number {
 }
 ```
 
-See `references/layout.md`.
+See `reference/layout.md`.
 
 ### 3. The screen is round; your layout is not
 
@@ -126,7 +128,7 @@ simulator's backlit LCD.
 Corollary: a saturated colour on a glyph reflects only its own channel, making
 the thing you want to read the *dimmest* thing on screen.
 
-See `references/display.md`.
+See `reference/display.md`.
 
 ### 5. The simulator lies about settings
 
@@ -137,14 +139,59 @@ settings code.
 
 Reset also drops the loaded device, so relaunch and re-push afterwards.
 
-See `references/simulator.md`.
+See `reference/simulator.md`.
+
+### 6. On AMOLED, the face you designed is the one that fails review
+
+`requiresBurnInProtection` devices must show a restricted always-on frame
+between wrist raises. The trap is that the *stronger* your face's identity —
+a bright panel, a filled dial — the worse a dimmed version of it performs,
+because it still lights most of the screen. The always-on frame has to be a
+different drawing: outlines where there were fills, and shifted a few pixels on
+a cycle so no pixel is driven continuously.
+
+Also note the flag can be **null** on older products, and a null propagating
+into a `Boolean` field throws at the first wrist drop.
+
+See the AMOLED section of `reference/display.md`.
+
+### 7. A watch face CAN have settings on the watch
+
+`AppBase.getSettingsView()` has existed since **API 3.2.0** and the SDK
+documents it as "only applicable to watch faces and data fields". Plenty of
+store copy — including, at one point, this author's own — claims settings are
+reachable only from the phone. They are not.
+
+The override signature must include `or Null` or the compiler rejects it as
+narrowing:
+
+```monkeyc
+function getSettingsView() as
+    [WatchUi.Views] or [WatchUi.Views, WatchUi.InputDelegates] or Null {
+    return [new SettingsMenu(), new SettingsMenuDelegate()];
+}
+```
+
+Two things to get right in the menu itself:
+
+- `ToggleMenuItem` has **already flipped its own state** by the time `onSelect`
+  runs. Read `isEnabled()`; negating the stored value inverts the setting.
+- A picker should `setFocus()` the current choice, not open at the top of a long
+  list. If the list filters out unavailable options, item position is *not* the
+  option id — count the focus row as you build the list.
+
+Keep one module that owns every property read, each wrapped with a default, and
+have both the phone path and the on-watch menu go through it. Two readers with
+two sets of defaults is exactly how the watch and the phone come to disagree
+about what "off" means — and check the fallbacks actually match
+`properties.xml`, because nothing enforces that.
 
 ## Workflow
 
 ### Starting a face
 
-1. `<skill-dir>/scripts/ciq-doctor` — confirm SDK, JDK, developer key, target device installed.
-2. Copy `<skill-dir>/templates/Makefile`, `<skill-dir>/templates/monkey.jungle`, `<skill-dir>/templates/monkey.test.jungle`.
+1. `bin/ciq-doctor` — confirm SDK, JDK, developer key, target device installed.
+2. Copy `templates/Makefile`, `templates/monkey.jungle`, `templates/monkey.test.jungle`.
 3. Generate a fresh app id: `python3 -c "import uuid;print(uuid.uuid4().hex)"`.
 4. Split source by responsibility. This structure has held up well:
 
@@ -173,7 +220,7 @@ Capture and *look at it*. Layout bugs are invisible in a passing test run:
 
 ```bash
 make build && make sim
-<skill-dir>/scripts/ciq-capture /tmp/face.png --face --size 260
+bin/ciq-capture /tmp/face.png --face --size 260
 ```
 
 Then Read the PNG. Every layout bug in this skill's history was found by looking,
@@ -206,7 +253,7 @@ are what makes it recognisable:
 - **Where the legends sit** — maker's name on the bezel, not the glass.
 
 No system font is a segment display. If you need one, draw it: see
-`references/layout.md` for a working seven-segment renderer, including the ghost
+`reference/layout.md` for a working seven-segment renderer, including the ghost
 (unlit) segments that are most of what sells the effect.
 
-**Do not print a real brand on the face.** See `references/store.md`.
+**Do not print a real brand on the face.** See `reference/store.md`.

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

@@ -0,0 +1,99 @@
+# Proposing a face in SVG before writing Monkey C
+
+A Monkey C iteration is a build, a simulator launch, a screenshot and a look:
+minutes. An SVG iteration is a file write: seconds. Every visual decision that
+can be made in SVG should be made there, because the ones that reach Monkey C
+get made once and then defended.
+
+The failures this prevents are the expensive ones -- a subdial layout that turns
+out to be unreadable, a status row that collides with the index band, a digit
+cell too small for the stroke inside it. All of those survive a green test suite
+and only show up in a capture.
+
+## The rule that makes a mock worth anything
+
+**An SVG mock must be constrained to what the panel can draw, or it is a lie.**
+
+A browser gives you 16.7 million colours, alpha, gradients, blur and free
+anti-aliasing. A fenix MIP panel gives you 64 colours on a 4x4x4 lattice, no
+alpha blending at all, and no anti-aliasing. A mock that uses the browser's
+extras gets approved and then cannot be implemented, and the gap is discovered
+after the geometry is already committed.
+
+`scripts/ciq-mock` exists to close that gap: it renders each proposal with every
+colour quantised to the lattice, inside the round bezel, and lists what will not
+survive.
+
+```bash
+<skill-dir>/scripts/ciq-mock /tmp/proposals.html a.svg b.svg c.svg --device fenix6pro
+```
+
+Then **open it and look at it**, the same way you would a simulator capture.
+
+## What to write, and what not to
+
+| Use | Not |
+| --- | --- |
+| `<rect>` `<circle>` `<line>` `<polygon>` `<path>` | `<image>`, `<pattern>` |
+| flat `fill` on the lattice | `<linearGradient>`, `<radialGradient>` |
+| `stroke-width` 2 or more | hairlines; a 1px diagonal is a dotted line |
+| solid colour to separate shapes | `opacity` / `fill-opacity` of any kind |
+| `<g transform="rotate(...)">` for hands | anything you cannot express as sin/cos |
+| `<text>` as a *placeholder* | `<text>` as a measurement |
+
+`<path>` is fine to draw with, but nothing in Monkey C consumes one: it has to
+become `fillPolygon`, `drawArc` or `drawLine`. If a shape cannot be decomposed
+into those, it is not a shape you can ship.
+
+`<text>` deserves its own warning. Browser font metrics are not device font
+metrics and never will be. Use text to reserve *approximate* space, then derive
+the real box from `dc.getFontHeight()` and `dc.getTextWidthInPixels()` at draw
+time. See `layout.md`.
+
+## The lattice
+
+`0x00 / 0x55 / 0xAA / 0xFF` per channel. Write colours on it directly and the
+mock and the watch agree. Write anything else and `ciq-mock` will tell you what
+it becomes -- usually a bigger jump than expected, and two carefully separated
+greys frequently collapse onto one.
+
+Rank by luminance, not by hue: on a transflective panel brightness *is*
+reflectance. See `display.md`.
+
+## The bezel
+
+`ciq-mock` checks the farthest point of every `rect`, `circle`, `ellipse`,
+`line`, `polygon` and `polyline` against the glass radius. It does **not** check
+`<path>` shapes -- that needs a real path renderer and remains unchecked -- and
+it does not validate text extents (font metrics come from the device, not the
+browser).
+
+The check that matters most is the rectangle one: a rectangle inscribed in a
+circle fails at its **corners** long before its sides, and the amount by which
+it fails is `sqrt(w^2 + h^2)/2`, not `w/2`. Radial markers have the same
+problem: a marker of width `w` ending at radius `r` actually reaches
+`sqrt(r^2 + (w/2)^2)`.
+
+## Proposing to a human
+
+Exactly three variants, not one and not seven. One is an ultimatum; seven is a survey.
+
+Make the three differ on **one axis you actually want an answer about** --
+information density, or dial polarity, or analog versus digital -- and hold
+everything else constant. Variants that differ in five ways at once produce
+"I like bits of each", which is not a decision.
+
+State what is fixed by the device (resolution, colour count, no alpha) so the
+feedback lands on choices rather than constraints, and say plainly that colours
+shown are post-quantisation.
+
+## After approval
+
+Freeze the chosen variant into constants before writing drawing code: every
+radius, every centre, every width, as named values in `Layout.mc`. The SVG is a
+picture; `Layout.mc` is the specification, and keeping it free of `Dc` calls is
+what makes the geometry unit-testable.
+
+Then re-derive the mock from those constants if you change them. A stale mock
+that no longer matches the code is worse than none, because it is what the human
+remembers approving.

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

@@ -90,9 +90,121 @@ does not "helpfully" add products:
      bezel. Another size or shape will compile and look wrong, not fail. -->
 ```
 
+## Launcher icons differ within a resolution family
+
+`ciq-devices --same-as <device>` prints this, and it is easy to skip past. Sizes
+seen in practice: 35×35 (vivoactive 4, the legacy hero editions), 40×40 (fenix
+6/7 at 260×260), 60×60 (descent mk3 51mm, epix 2 pro 51mm), 65×65 (the 454×454
+AMOLED group).
+
+Give each size its own `resourcePath` in the jungle, listed *after* the base so
+its drawables win:
+
+```
+fr970.resourcePath = $(base.resourcePath);resources-65
+```
+
+**Do not upsample.** A 40×40 icon scaled to 65×65 turns 2px segment bars into
+grey smears. Draw it at size — render at 8× and downsample once with a good
+filter, which is what gives rounded corners and stroke ends clean edges at these
+sizes. Keep the generator in `tools/` so the next size is one command.
+
+## Making `Layout` resolution-aware
+
+Worth doing once a face has traction, and much less risky than it sounds if you
+treat the original numbers as a **design grid** rather than replacing them:
+
+```monkeyc
+const DESIGN = 260;              // a unit, not a screen size
+var FRAME_W as Number = 204;     // var, not const -- init() rewrites these
+
+// Round, don't truncate: truncation biases every constant down by up to a
+// pixel, and across a gasket and two insets that is a visible seam.
+function grid(value as Number) as Number {
+    return ((value * SCREEN) + (DESIGN / 2)) / DESIGN;
+}
+
+function init(width as Number) as Void {
+    SCREEN = width;
+    CENTER = width / 2;
+    FRAME_W = grid(204);
+    // ...
+    if (STROKE < 1) { STROKE = 1; }   // a stroke rounded to 0 draws nothing
+}
+```
+
+Call it from `onLayout(dc)` with `dc.getWidth()` — never from a device name, so
+a new product needs no code at all.
+
+**Constants outside `Layout.mc` are the trap.** Widget modules accumulate their
+own pixel values -- an arc radius, a digit cell, a gap -- and a design-grid
+conversion that only edits `Layout.mc` leaves every one of them at the old size.
+The result compiles, passes every test, and renders as a small face marooned in
+the middle of a larger screen. Grep the whole `source/` tree for numeric
+constants, not just the geometry module, and give each widget its own `build()`
+called from `onLayout` after `Layout.init`. Exclude angles and bit masks: a
+sweep is 270 degrees at every size.
+
+Three things this gets wrong if you are not careful:
+
+1. **Relational tests keep passing at the new size but prove nothing new.** Most
+   layout assertions are written as comparisons, so they hold at any scale
+   *given whatever Layout currently holds*. Add a test that sweeps every shipped
+   resolution, calling `init()` for each and restoring the design grid on exit.
+2. **A scale function that ignored its argument would pass all of those.** Pin
+   growth explicitly: 204 on the grid must land near 356 at 454.
+3. **Rounding direction is untested by default.** Assert `grid(1) == 2` at 454,
+   not just `grid(1) >= 1`.
+
+### Derived constants are baked at compile time
+
+This is the one that will cost you an afternoon. A constant defined in terms of
+another constant is evaluated ONCE, at build time, from the design-grid values:
+
+```monkeyc
+const SUB_N_X = CENTER;              // baked as 130, forever
+const SUB_N_Y = CENTER - SUB_OFFSET; // baked as 78
+```
+
+`init()` rewriting `CENTER` does not move them. On a 454 screen every one of
+those subdials stayed clustered in the top-left corner, on top of each other and
+the crest, while the chapter ring and hands scaled perfectly. It compiled, and
+every test passed.
+
+Convert them to `var` and recompute them at the END of `init()`, after
+everything they depend on is set.
+
+**Give them real design-grid defaults, not 0.** Unit tests never call `init()`,
+so a derived var initialised to 0 reads as `band 0` in assertions that were
+previously passing for the right reason. Four layout tests failed that way, and
+the failure looks like a geometry regression rather than an initialisation
+order problem.
+
+### A checklist for the whole conversion
+
+Grep the entire `source/` tree, not just `Layout.mc`:
+
+```bash
+grep -rn "const [A-Z_][A-Z_0-9]* =" source/
+```
+
+Then sort what you find into three buckets:
+
+| Bucket | Examples | Scale? |
+| --- | --- | --- |
+| Lengths | radii, widths, offsets, gaps, Y positions | **yes** |
+| Counts | station count, rows, bars, ticks | never |
+| Angles and masks | sweep degrees, start angle, `SEG_A = 0x01` | never |
+
+Scaling a count deforms the dial rather than resizing it, and scaling a bitmask
+produces garbage. Both compile.
+
 ## Recommended order
 
 1. Ship one resolution, verified on your own wrist.
 2. Add the same-resolution family — biggest reach per unit of risk.
 3. Make `Layout` resolution-aware only if it gets traction. It is real work and
    it risks the pixel-exact look you tuned.
+4. Crossing to AMOLED is a *separate* step from crossing resolution, even though
+   the 454×454 group makes them arrive together. See the always-on section in
+   `reference/display.md` — that is the part that fails review, not the layout.

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

@@ -115,6 +115,81 @@ function panelIsLighterThanItsSegments(logger as Logger) as Boolean {
 
 ## AMOLED devices
 
-Venu and newer devices are emissive and do not share these constraints, but they
-do have burn-in protection requirements and an always-on mode with a pixel budget.
-Do not carry MIP palette reasoning onto them unexamined.
+Venu, Forerunner 265/965/970, fenix 8 (non-solar) and epix are **emissive**.
+Almost every rule above inverts, and the one that matters most is not about
+colour at all.
+
+Read the device rather than guessing — `compiler.json` carries `displayType`,
+`bitsPerPixel` and `alphaBlendingSupport`:
+
+| | fenix 6 Pro | Forerunner 970 |
+| --- | --- | --- |
+| `displayType` | `mip` | `amoled` |
+| Resolution | 260×260 | 454×454 |
+| `bitsPerPixel` | 8 | 16 |
+| `alphaBlendingSupport` | false | **true** |
+| Launcher icon | 40×40 | **65×65** |
+
+So on AMOLED you get anti-aliasing and real colour, and the 4×4×4 lattice stops
+being a constraint. Lattice colours still render correctly, so a palette tuned
+for MIP is safe to ship to both — it is merely conservative.
+
+### The always-on frame is the whole problem
+
+`System.getDeviceSettings().requiresBurnInProtection` is true on these devices.
+Between wrist raises the face must show a restricted frame: a small fraction of
+pixels lit, and not always the *same* pixels. Garmin rejects faces that ignore
+this.
+
+The property arrived after some supported products shipped and **can be null**,
+so check both the symbol and the value — a null flowing into a `Boolean` field
+throws at the first wrist drop:
+
+```monkeyc
+private function needsAlwaysOn() as Boolean {
+    var s = System.getDeviceSettings();
+    if (!(s has :requiresBurnInProtection)) { return false; }
+    var flag = s.requiresBurnInProtection;
+    return flag != null && flag;
+}
+```
+
+**The always-on frame is a different drawing, not a dimmed one.** This is the
+part that bites: if the face's identity is a large bright area — a lit LCD
+panel, a white dial, a filled gauge — then dimming it still lights most of the
+screen. Reach instead for what the real object looks like with the power off.
+An outline where there was a fill; strokes where there was a panel.
+
+Budget check: on 454×454 (206k pixels), seven-segment strokes for four digits
+plus a 1px frame outline is roughly 2% lit. A filled rounded rectangle the size
+of that frame alone is 40k pixels — 19%.
+
+### Move the lit pixels
+
+Static content burns the pixel even at low duty. Shift the whole block by a few
+pixels on a cycle, and make the horizontal and vertical periods **coprime** so
+the pair does not return to the same offset every few minutes:
+
+```monkeyc
+const SHIFT_PERIOD = 7;      // x
+const SHIFT_PERIOD_Y = 5;    // y  -> 35 distinct positions, not 7
+
+function shiftX(minute as Number) as Number {
+    return (minute % SHIFT_PERIOD) - (SHIFT_PERIOD / 2);
+}
+```
+
+Both periods dividing into 60 is the trap: with 6 and 3 you get 6 positions and
+park a segment edge on the same pixels ten times an hour.
+
+Test the arithmetic even though you cannot test the drawing — that the offsets
+stay small enough to keep content on screen, that **every** offset in range is
+actually visited (a `shiftX` stuck at 0 passes "stays small" and protects
+nothing), and that the (x, y) pair yields the full period.
+
+### Helpers that pick their own colour
+
+Segment and hand renderers commonly call `dc.setColor(Palette.SEGMENT, ...)`
+internally. Reusing them for the always-on frame silently repaints it in the
+lit-face colour. Either pass the colour in, or draw the always-on frame against
+the mask primitives directly.

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

@@ -0,0 +1,140 @@
+# Wizard mode: from "make me a watch face" to a frozen spec
+
+Use this when the brief is a mood rather than a design -- "something modern",
+"like a chronograph", "match my brand". Do not use it when the user already
+knows what they want; skip to `design-proposals.md`.
+
+The wizard is five stages and **two** questions to the human. Stopping at every
+stage for approval is how a design session becomes a survey; stopping at none is
+how you build the wrong face beautifully.
+
+The order below is the point. Constraints come before ideas, because the device
+facts invalidate whole categories of idea and it is cheaper to lose them now.
+
+---
+
+## Stage 0 -- Constraints, before a single idea
+
+```bash
+<skill-dir>/scripts/ciq-doctor
+<skill-dir>/scripts/ciq-devices --same-as <target>
+```
+
+Then read the target's `compiler.json` yourself and write down four numbers:
+
+| Fact | Why it kills ideas |
+| --- | --- |
+| resolution + shape | the round bezel eliminates most rectangular layouts |
+| `bitsPerPixel` | 8bpp is 64 colours; photographic anything is out |
+| `alphaBlendingSupport` | almost always false: no translucency, no soft edges |
+| `watchFace` memoryLimit | typically ~112 KB: vector only, no bitmap dial |
+
+A face conceived without these gets redesigned after it is built.
+
+---
+
+## Stage 1 -- Gather
+
+```bash
+<skill-dir>/scripts/ciq-inspire --brand acme.com --json /tmp/tokens.json
+<skill-dir>/scripts/ciq-inspire --image ~/crest.png
+<skill-dir>/scripts/ciq-inspire --prior-art "chronograph"
+```
+
+Three axes worth gathering along:
+
+- **Object** -- if there is a real watch or instrument behind the brief, its
+  proportions and polarity are what make it recognisable. Get those first; see
+  the homage section in `SKILL.md`.
+- **Palette** -- from a brand domain, or from an image the user already owns.
+  Everything comes back quantised, so what you show is what ships.
+- **Prior art** -- read other people's Monkey C for *technique*, not for code.
+  Most Connect IQ repositories carry no licence, which means all rights
+  reserved.
+
+**IP boundary.** Use brand research and design references as inspiration only:
+implementation must be original, and distinctive creative elements or
+compositions must not be copied verbatim. Names, wordmarks and logos are not
+permissible -- not in the face, the launcher icon, the screenshots or the copy.
+`ciq-inspire --brand` will return another company's logo without complaint; that
+is a research artefact, not an asset. See `store.md`.
+
+---
+
+## Stage 2 -- Question one: the axis
+
+Ask the human **one** question, with three or four concrete options, about the
+axis you cannot infer. In practice it is nearly always one of:
+
+| Axis | Options that actually differ |
+| --- | --- |
+| Form | analog hands / digital numerals / hybrid |
+| Density | core metrics only / moderate / dense |
+| Polarity | dark dial, bright ink / light dial, dark ink |
+| Character | instrument, tactical, minimal, retro homage |
+
+Alongside it, settle the boring-but-load-bearing ones in the same breath,
+because each changes the code shape rather than the look:
+
+- **Which devices.** One device is a manifest line; a second resolution is a
+  second layout. Widening later is cheap only if you stayed vector-only.
+- **Sweeping seconds.** This is a battery decision, not an aesthetic one. It
+  forces `onPartialUpdate`, a 20 ms budget, clip-box arithmetic and an
+  `onPowerBudgetExceeded` fallback ladder. Costs roughly a third of the build.
+- **Settings.** Themes and toggles mean `properties.xml`, `settings.xml`, and
+  the simulator's habit of ignoring changed defaults. Also: watch face settings
+  are unreachable from the watch, only from the phone app -- if you add them,
+  the listing has to say so or every user reports them missing.
+
+---
+
+## Stage 3 -- Diverge: exactly three variants as SVG
+
+Write exactly three SVG files that differ on **the one axis you asked about**,
+holding everything else constant. Then:
+
+```bash
+<skill-dir>/scripts/ciq-mock /tmp/proposals.html a.svg b.svg c.svg --device <target>
+```
+
+Read `design-proposals.md` before writing the SVG -- the constraints there are
+what stop a mock promising something the panel cannot render. Open the HTML and
+look at it yourself before showing anyone. Fix anything the audit flags; an
+approved design with a bezel violation in it is a design that will be quietly
+changed later.
+
+Density is where these get decided in practice. The most-cited reason people
+uninstall a fenix face is data crammed in too small to read -- so if the
+variants differ in density, the dense one must be honestly dense, at real font
+sizes, or the comparison is rigged.
+
+---
+
+## Stage 4 -- Question two: converge
+
+Show the sheet. Ask which variant, and what to change about it. Expect the
+answer to be "B, but with A's date placement" -- that is a good answer and it is
+why the variants held everything else constant.
+
+Do **one** revision round, re-run `ciq-mock`, and stop. A third round means the
+axis in Stage 2 was the wrong one; go back and ask a better question rather than
+iterating on pixels.
+
+---
+
+## Stage 5 -- Freeze
+
+Turn the approved picture into a specification before writing drawing code:
+
+- every radius, centre, width and offset as a named constant in `Layout.mc`
+- the palette as **roles** (`DIAL`, `RULE`, `INDEX`, `HAND`, `ACCENT`), not as
+  colour names, so a second theme is a table row rather than a rewrite
+- the draw order, written down -- a later fill erases an earlier ring
+- the two or three places where the layout is nearly out of room, with the
+  remedy already chosen, so the fix later is not an ad-hoc nudge
+
+Keep `Layout.mc` free of `Dc` calls. That is what lets the geometry be
+unit-tested against the bezel across the full sweep, which is the only automated
+check that catches a clipped layout.
+
+Then, and only then, start Phase 0 of the build.