@olegkoval/agent-skills 1.19.1 → 1.21.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-agent-skills",
   "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, and other skill-aware tools.",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "author": {
     "name": "Oleg Koval"
   },
@@ -32,6 +32,8 @@
     "./packages/software-development/macos-menubar-app",
     "./packages/software-development/skill-budget-audit",
     "./packages/software-development/crash-course",
-    "./packages/software-development/qodoloop"
+    "./packages/software-development/qodoloop",
+    "./packages/wearables/garmin-watchface",
+    "./packages/software-development/coderabbitloop"
   ]
 }

package/.cursor-plugin/index.json

@@ -110,6 +110,16 @@
       "name": "olko:qodoloop",
       "source": "./packages/software-development/qodoloop/adapters/cursor",
       "description": "Iteratively drives a GitHub PR to zero unresolved Qodo findings — reads each finding's own Agent Prompt, applies the fix, replies to the thread, resolves it, pushes, and waits for Qodo's next pass."
+    },
+    {
+      "name": "olko:garmin-watchface",
+      "source": "./packages/wearables/garmin-watchface/adapters/cursor",
+      "description": "Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C."
+    },
+    {
+      "name": "olko:coderabbitloop",
+      "source": "./packages/software-development/coderabbitloop/adapters/cursor",
+      "description": "Iteratively drives a GitHub PR to zero unresolved CodeRabbit findings — reads each inline comment's own Prompt for AI Agents block, applies the fix, replies to the thread, resolves it, pushes, and re-triggers CodeRabbit."
     }
   ]
 }

package/.grok-plugin/index.json

@@ -120,6 +120,16 @@
       "name": "olko:qodoloop",
       "source": "./packages/software-development/qodoloop/adapters/grok",
       "description": "Iteratively drives a GitHub PR to zero unresolved Qodo findings — reads each finding's own Agent Prompt, applies the fix, replies to the thread, resolves it, pushes, and waits for Qodo's next pass."
+    },
+    {
+      "name": "olko:garmin-watchface",
+      "source": "./packages/wearables/garmin-watchface/adapters/grok",
+      "description": "Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C."
+    },
+    {
+      "name": "olko:coderabbitloop",
+      "source": "./packages/software-development/coderabbitloop/adapters/grok",
+      "description": "Iteratively drives a GitHub PR to zero unresolved CodeRabbit findings — reads each inline comment's own Prompt for AI Agents block, applies the fix, replies to the thread, resolves it, pushes, and re-triggers CodeRabbit."
     }
   ]
 }

package/.kiro/steering/coderabbitloop.md

@@ -0,0 +1,109 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Iteratively drives a GitHub PR to zero unresolved CodeRabbit findings — reads each inline comment's own Prompt for AI Agents block, applies the fix, replies to the thread, resolves it, pushes, and re-triggers CodeRabbit."
+---
+
+# Coderabbitloop
+
+Fix every actionable CodeRabbit finding on a PR, answer each thread, resolve it, and keep going until CodeRabbit has nothing left to say (or a finding needs a human call).
+
+## Inputs
+
+- **PR number** (optional): detect from the current branch if not given.
+
+## How CodeRabbit actually posts (verified against docs.coderabbit.ai and a live install — don't assume otherwise)
+
+CodeRabbit runs as `coderabbitai[bot]` and posts **two independent things**, not one:
+
+1. An auto-generated **walkthrough/summary issue comment** — body starts with the HTML marker `<!-- This is an auto-generated comment: summarize by coderabbit.ai -->`. This is a description, not a review — use it for context only, never as a source of fixable findings.
+2. A **formal PR review** carrying one **inline review comment per finding**, each a real, resolvable GitHub review thread at the finding's file/line. Each one contains a `<details><summary>🤖 Prompt for AI Agents</summary>` block: a ready-made fix spec, CodeRabbit's own words, meant to be handed straight to an agent.
+
+**Use the inline threads as the source of truth**, exactly like Greptile/Qodo — fetch via GraphQL `reviewThreads`, which carries native `isResolved` state (see `references/graphql-queries.md`, shared with `qodoloop`; only the bot login and the prompt-heading text differ).
+
+CodeRabbit has slash commands (official, `docs.coderabbit.ai/reference/review-commands`) — the ones this loop actually uses:
+- `@coderabbitai review` — incremental review of new changes (use this to re-trigger after a push, if automatic review-on-push is off for this repo).
+- `@coderabbitai resolve` — marks **all** CodeRabbit threads resolved in one shot. This is a bulk escape hatch, not the default path: this loop resolves threads one at a time, right after replying to each, so the reply-then-resolve record stays intact per finding.
+- CodeRabbit also has its own built-in `@coderabbitai autofix`, which commits fixes directly without a model in the loop. Mention it to the user as an alternative if they'd rather skip the loop entirely, but this skill's whole point is the Claude-orchestrated version — don't default to autofix instead of doing the work.
+
+**Rate limit is a real terminal state, not a bug.** A comment reading "you've reached your PR review limit" (confirmed live wording) means CodeRabbit will not review again this cycle — stop and report it, don't loop waiting for something that isn't coming.
+
+## Instructions
+
+### 1. Identify the PR
+
+```bash
+gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
+```
+
+Check out the branch if not already on it.
+
+### 2. Loop (max 5 iterations)
+
+#### A. Push and wait
+
+```bash
+git push
+```
+
+If this repo doesn't auto-review on push, nudge it:
+
+```bash
+gh pr comment <PR_NUMBER> --body "@coderabbitai review"
+```
+
+Poll (every ~10s, timeout ~5min) for CodeRabbit's next formal review to land — a new entry in `gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews` from `coderabbitai[bot]` created after this push. If you instead see a rate-limit comment ("review limit"), **stop the loop now** and go to Report with `blocked: rate-limited`.
+
+#### B. Fetch unresolved findings
+
+Run the `unresolvedQodoThreads`-shaped query in `references/graphql-queries.md` (filter `author.login == "coderabbitai[bot]"` instead of Qodo's login). For each unresolved thread, parse the finding text and the **Prompt for AI Agents** block (heading text is `🤖 Prompt for AI Agents`, not `Agent Prompt` — match case/emoji-insensitively).
+
+#### C. Check exit conditions
+
+Stop if there are zero unresolved CodeRabbit threads, or max iterations reached.
+
+#### D. Fix each finding
+
+For each thread, in order: read the Prompt for AI Agents block in full — it names the issue and the fix. Apply it, staying inside its stated scope. If the suggestion is wrong, unsafe, or needs a product decision, don't force it — note that in step E instead.
+
+#### E. Answer and resolve
+
+**Reply to the thread first, then resolve it** — the "answer to the comments" half of the job:
+
+```bash
+gh api graphql -f query='mutation { addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: "<THREAD_ID>", body: "<REPLY>"}) { comment { id } } }'
+```
+
+Reply body: one or two sentences — what you changed and why, or exactly why you didn't fix it. Then resolve (`resolveReviewThread`). A finding you deliberately skip still gets a reply and gets resolved.
+
+#### F. Commit and push
+
+```bash
+git add -A
+git commit -m "address CodeRabbit review feedback (coderabbitloop iteration N)"
+git push
+```
+
+Go back to step A.
+
+### 3. Report
+
+| Field              | Value |
+|--------------------|-------|
+| Iterations         | N     |
+| Findings resolved  | N     |
+| Findings skipped   | N (with reasons) |
+| Remaining          | N (if any) |
+| Blocked            | rate-limited / max-iterations / none |
+
+```
+Coderabbitloop complete.
+  Iterations:  2
+  Resolved:    4 (3 fixed, 1 false-positive, replied + resolved)
+  Remaining:   0
+```
+
+## References
+
+- `references/graphql-queries.md` — shared with `qodoloop`: the exact `reviewThreads` query and the `resolveReviewThread` / `addPullRequestReviewThreadReply` mutations. Swap the author-login filter to `coderabbitai[bot]` and the prompt-heading match to `Prompt for AI Agents`.

package/.kiro/steering/garmin-watchface.md

@@ -0,0 +1,201 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C."
+---
+
+# Garmin Connect IQ watch faces
+
+Monkey C gives you almost no safety net. The compiler is happy to build a face
+that draws off the bottom of the screen, a test suite that contains no tests, and
+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.**
+
+| 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 |
+
+## 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-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
+
+### 1. `make test` can compile zero tests and report success
+
+If `monkey.jungle` sets `base.excludeAnnotations = test`, every `(:test)`
+function is stripped from **every** target, including the unit-test build. You
+get `BUILD SUCCESSFUL` and a green run with nothing compiled — even when the test
+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`.
+
+**Prove it before you trust it.** Put a deliberately unresolvable symbol in one
+test and confirm the build fails:
+
+```monkeyc
+return ThisDoesNotExist.definitelyNotAFunction();
+```
+
+### 2. Never hardcode a Y coordinate or assume a font height
+
+`dc.getFontHeight()` is the only source of truth, and the numbers are larger than
+they look. Measured on fenix 6 Pro:
+
+| Font | Height |
+| --- | --- |
+| `FONT_XTINY` | 19 |
+| `FONT_TINY` | 29 |
+| `FONT_SMALL` | 32 |
+| `FONT_NUMBER_MEDIUM` | 74 |
+
+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.
+
+Derive every Y at draw time, and **clamp** so a bottom row cannot be pushed off:
+
+```monkeyc
+function clampRuleY(derived as Number, footerH as Number) as Number {
+    var reserved = (footerH * 2) + GAP_BELOW_RULE + GAP_BETWEEN_ROWS;
+    var maxRuleY = SCREEN - BOTTOM_MARGIN - reserved;
+    return derived > maxRuleY ? maxRuleY : derived;
+}
+```
+
+See `references/layout.md`.
+
+### 3. The screen is round; your layout is not
+
+Check content against the bezel curve, not the bounding square. A rectangle
+inscribed in a circle fails at its **corners** long before its sides.
+
+```monkeyc
+function halfWidthAt(y as Number) as Number {
+    var dy = y - CENTER;
+    var inside = (CENTER * CENTER) - (dy * dy);
+    return inside <= 0 ? 0 : Math.sqrt(inside).toNumber();
+}
+```
+
+### 4. Colours are quantised, and brightness is reflectance
+
+Many devices snap to a 4×4×4 lattice: `0x00 / 0x55 / 0xAA / 0xFF` per channel. A
+colour not already on it is not the colour that ships.
+
+More important: MIP screens are **transflective with no backlight**. A colour's
+brightness *is* how much ambient light it returns. Grey reflects about two-thirds
+of what white does. Choosing a photographically accurate grey for a large area
+makes the whole face read as dim on the wrist while looking fine in the
+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`.
+
+### 5. The simulator lies about settings
+
+It persists app settings and **ignores changed defaults in `properties.xml`**
+until you do File → Reset All App Data. A property will keep reading its old
+value while the XML plainly says otherwise. This looks exactly like broken
+settings code.
+
+Reset also drops the loaded device, so relaunch and re-push afterwards.
+
+See `references/simulator.md`.
+
+## 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`.
+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:
+
+| Module | Holds |
+| --- | --- |
+| `Palette.mc` | Colours only, all lattice-exact |
+| `Layout.mc` | Geometry, derivations, bezel maths — no drawing |
+| `<Widget>.mc` | Drawing primitives (rows, bars, segments) |
+| `Fields.mc` | Formatting and thresholds — pure, easy to test |
+| `Sensors.mc` | Sensor reads with null handling |
+| `<Name>View.mc` | Composition only |
+
+Keeping `Layout` free of `Dc` calls is what makes geometry unit-testable.
+
+### Every change
+
+```bash
+make build && make test && make lint
+```
+
+`make lint` is level 3 and catches real problems the level 2 build allows.
+
+### Before committing
+
+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
+```
+
+Then Read the PNG. Every layout bug in this skill's history was found by looking,
+not by testing.
+
+## Monkey C gotchas
+
+- Module-level functions take **no** visibility modifier. `private` and `hidden`
+  are class-only; at module scope they are syntax errors.
+- `dc.fillPolygon` wants `Array<[Numeric, Numeric]>`. Cast the literal:
+  `[[x, y], ...] as Array<[Numeric, Numeric]>`.
+- `getInitialView()` returns
+  `[WatchUi.Views] or [WatchUi.Views, WatchUi.InputDelegates]`.
+- `Application.Properties.getValue()` **throws** when a key is absent, which
+  happens on a fresh install before settings have ever been written. Wrap every
+  read with a default.
+- Integer division everywhere. Centring an odd width leaves a 1px skew — write
+  tests that allow it rather than forcing constants to stay even.
+
+## Reference watches and homages
+
+If reproducing a real object, get these right before anything else, because they
+are what makes it recognisable:
+
+- **Display polarity.** A 1970s LCD is *positive*: dark segments on a pale panel,
+  the inverse of every modern face. Getting this backwards turns a crystal into a
+  screen.
+- **Proportion.** Bezels on vintage digitals are thick; the window is smaller
+  than memory suggests.
+- **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
+(unlit) segments that are most of what sells the effect.
+
+**Do not print a real brand on the face.** See `references/store.md`.

package/.windsurf/rules/coderabbitloop.md

@@ -0,0 +1,108 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Iteratively drives a GitHub PR to zero unresolved CodeRabbit findings — reads each inline comment's own Prompt for AI Agents block, applies the fix, replies to the thread, resolves it, pushes, and re-triggers CodeRabbit."
+---
+
+# Coderabbitloop
+
+Fix every actionable CodeRabbit finding on a PR, answer each thread, resolve it, and keep going until CodeRabbit has nothing left to say (or a finding needs a human call).
+
+## Inputs
+
+- **PR number** (optional): detect from the current branch if not given.
+
+## How CodeRabbit actually posts (verified against docs.coderabbit.ai and a live install — don't assume otherwise)
+
+CodeRabbit runs as `coderabbitai[bot]` and posts **two independent things**, not one:
+
+1. An auto-generated **walkthrough/summary issue comment** — body starts with the HTML marker `<!-- This is an auto-generated comment: summarize by coderabbit.ai -->`. This is a description, not a review — use it for context only, never as a source of fixable findings.
+2. A **formal PR review** carrying one **inline review comment per finding**, each a real, resolvable GitHub review thread at the finding's file/line. Each one contains a `<details><summary>🤖 Prompt for AI Agents</summary>` block: a ready-made fix spec, CodeRabbit's own words, meant to be handed straight to an agent.
+
+**Use the inline threads as the source of truth**, exactly like Greptile/Qodo — fetch via GraphQL `reviewThreads`, which carries native `isResolved` state (see `references/graphql-queries.md`, shared with `qodoloop`; only the bot login and the prompt-heading text differ).
+
+CodeRabbit has slash commands (official, `docs.coderabbit.ai/reference/review-commands`) — the ones this loop actually uses:
+- `@coderabbitai review` — incremental review of new changes (use this to re-trigger after a push, if automatic review-on-push is off for this repo).
+- `@coderabbitai resolve` — marks **all** CodeRabbit threads resolved in one shot. This is a bulk escape hatch, not the default path: this loop resolves threads one at a time, right after replying to each, so the reply-then-resolve record stays intact per finding.
+- CodeRabbit also has its own built-in `@coderabbitai autofix`, which commits fixes directly without a model in the loop. Mention it to the user as an alternative if they'd rather skip the loop entirely, but this skill's whole point is the Claude-orchestrated version — don't default to autofix instead of doing the work.
+
+**Rate limit is a real terminal state, not a bug.** A comment reading "you've reached your PR review limit" (confirmed live wording) means CodeRabbit will not review again this cycle — stop and report it, don't loop waiting for something that isn't coming.
+
+## Instructions
+
+### 1. Identify the PR
+
+```bash
+gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
+```
+
+Check out the branch if not already on it.
+
+### 2. Loop (max 5 iterations)
+
+#### A. Push and wait
+
+```bash
+git push
+```
+
+If this repo doesn't auto-review on push, nudge it:
+
+```bash
+gh pr comment <PR_NUMBER> --body "@coderabbitai review"
+```
+
+Poll (every ~10s, timeout ~5min) for CodeRabbit's next formal review to land — a new entry in `gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews` from `coderabbitai[bot]` created after this push. If you instead see a rate-limit comment ("review limit"), **stop the loop now** and go to Report with `blocked: rate-limited`.
+
+#### B. Fetch unresolved findings
+
+Run the `unresolvedQodoThreads`-shaped query in `references/graphql-queries.md` (filter `author.login == "coderabbitai[bot]"` instead of Qodo's login). For each unresolved thread, parse the finding text and the **Prompt for AI Agents** block (heading text is `🤖 Prompt for AI Agents`, not `Agent Prompt` — match case/emoji-insensitively).
+
+#### C. Check exit conditions
+
+Stop if there are zero unresolved CodeRabbit threads, or max iterations reached.
+
+#### D. Fix each finding
+
+For each thread, in order: read the Prompt for AI Agents block in full — it names the issue and the fix. Apply it, staying inside its stated scope. If the suggestion is wrong, unsafe, or needs a product decision, don't force it — note that in step E instead.
+
+#### E. Answer and resolve
+
+**Reply to the thread first, then resolve it** — the "answer to the comments" half of the job:
+
+```bash
+gh api graphql -f query='mutation { addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: "<THREAD_ID>", body: "<REPLY>"}) { comment { id } } }'
+```
+
+Reply body: one or two sentences — what you changed and why, or exactly why you didn't fix it. Then resolve (`resolveReviewThread`). A finding you deliberately skip still gets a reply and gets resolved.
+
+#### F. Commit and push
+
+```bash
+git add -A
+git commit -m "address CodeRabbit review feedback (coderabbitloop iteration N)"
+git push
+```
+
+Go back to step A.
+
+### 3. Report
+
+| Field              | Value |
+|--------------------|-------|
+| Iterations         | N     |
+| Findings resolved  | N     |
+| Findings skipped   | N (with reasons) |
+| Remaining          | N (if any) |
+| Blocked            | rate-limited / max-iterations / none |
+
+```
+Coderabbitloop complete.
+  Iterations:  2
+  Resolved:    4 (3 fixed, 1 false-positive, replied + resolved)
+  Remaining:   0
+```
+
+## References
+
+- `references/graphql-queries.md` — shared with `qodoloop`: the exact `reviewThreads` query and the `resolveReviewThread` / `addPullRequestReviewThreadReply` mutations. Swap the author-login filter to `coderabbitai[bot]` and the prompt-heading match to `Prompt for AI Agents`.

package/.windsurf/rules/garmin-watchface.md

@@ -0,0 +1,200 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C."
+---
+
+# Garmin Connect IQ watch faces
+
+Monkey C gives you almost no safety net. The compiler is happy to build a face
+that draws off the bottom of the screen, a test suite that contains no tests, and
+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.**
+
+| 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 |
+
+## 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-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
+
+### 1. `make test` can compile zero tests and report success
+
+If `monkey.jungle` sets `base.excludeAnnotations = test`, every `(:test)`
+function is stripped from **every** target, including the unit-test build. You
+get `BUILD SUCCESSFUL` and a green run with nothing compiled — even when the test
+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`.
+
+**Prove it before you trust it.** Put a deliberately unresolvable symbol in one
+test and confirm the build fails:
+
+```monkeyc
+return ThisDoesNotExist.definitelyNotAFunction();
+```
+
+### 2. Never hardcode a Y coordinate or assume a font height
+
+`dc.getFontHeight()` is the only source of truth, and the numbers are larger than
+they look. Measured on fenix 6 Pro:
+
+| Font | Height |
+| --- | --- |
+| `FONT_XTINY` | 19 |
+| `FONT_TINY` | 29 |
+| `FONT_SMALL` | 32 |
+| `FONT_NUMBER_MEDIUM` | 74 |
+
+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.
+
+Derive every Y at draw time, and **clamp** so a bottom row cannot be pushed off:
+
+```monkeyc
+function clampRuleY(derived as Number, footerH as Number) as Number {
+    var reserved = (footerH * 2) + GAP_BELOW_RULE + GAP_BETWEEN_ROWS;
+    var maxRuleY = SCREEN - BOTTOM_MARGIN - reserved;
+    return derived > maxRuleY ? maxRuleY : derived;
+}
+```
+
+See `references/layout.md`.
+
+### 3. The screen is round; your layout is not
+
+Check content against the bezel curve, not the bounding square. A rectangle
+inscribed in a circle fails at its **corners** long before its sides.
+
+```monkeyc
+function halfWidthAt(y as Number) as Number {
+    var dy = y - CENTER;
+    var inside = (CENTER * CENTER) - (dy * dy);
+    return inside <= 0 ? 0 : Math.sqrt(inside).toNumber();
+}
+```
+
+### 4. Colours are quantised, and brightness is reflectance
+
+Many devices snap to a 4×4×4 lattice: `0x00 / 0x55 / 0xAA / 0xFF` per channel. A
+colour not already on it is not the colour that ships.
+
+More important: MIP screens are **transflective with no backlight**. A colour's
+brightness *is* how much ambient light it returns. Grey reflects about two-thirds
+of what white does. Choosing a photographically accurate grey for a large area
+makes the whole face read as dim on the wrist while looking fine in the
+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`.
+
+### 5. The simulator lies about settings
+
+It persists app settings and **ignores changed defaults in `properties.xml`**
+until you do File → Reset All App Data. A property will keep reading its old
+value while the XML plainly says otherwise. This looks exactly like broken
+settings code.
+
+Reset also drops the loaded device, so relaunch and re-push afterwards.
+
+See `references/simulator.md`.
+
+## 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`.
+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:
+
+| Module | Holds |
+| --- | --- |
+| `Palette.mc` | Colours only, all lattice-exact |
+| `Layout.mc` | Geometry, derivations, bezel maths — no drawing |
+| `<Widget>.mc` | Drawing primitives (rows, bars, segments) |
+| `Fields.mc` | Formatting and thresholds — pure, easy to test |
+| `Sensors.mc` | Sensor reads with null handling |
+| `<Name>View.mc` | Composition only |
+
+Keeping `Layout` free of `Dc` calls is what makes geometry unit-testable.
+
+### Every change
+
+```bash
+make build && make test && make lint
+```
+
+`make lint` is level 3 and catches real problems the level 2 build allows.
+
+### Before committing
+
+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
+```
+
+Then Read the PNG. Every layout bug in this skill's history was found by looking,
+not by testing.
+
+## Monkey C gotchas
+
+- Module-level functions take **no** visibility modifier. `private` and `hidden`
+  are class-only; at module scope they are syntax errors.
+- `dc.fillPolygon` wants `Array<[Numeric, Numeric]>`. Cast the literal:
+  `[[x, y], ...] as Array<[Numeric, Numeric]>`.
+- `getInitialView()` returns
+  `[WatchUi.Views] or [WatchUi.Views, WatchUi.InputDelegates]`.
+- `Application.Properties.getValue()` **throws** when a key is absent, which
+  happens on a fresh install before settings have ever been written. Wrap every
+  read with a default.
+- Integer division everywhere. Centring an odd width leaves a 1px skew — write
+  tests that allow it rather than forcing constants to stay even.
+
+## Reference watches and homages
+
+If reproducing a real object, get these right before anything else, because they
+are what makes it recognisable:
+
+- **Display polarity.** A 1970s LCD is *positive*: dark segments on a pale panel,
+  the inverse of every modern face. Getting this backwards turns a crystal into a
+  screen.
+- **Proportion.** Bezels on vintage digitals are thick; the window is smaller
+  than memory suggests.
+- **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
+(unlit) segments that are most of what sells the effect.
+
+**Do not print a real brand on the face.** See `references/store.md`.