claude-mcp-workflow 0.1.8 → 0.1.9

package/templates/skills/lang-python/SKILL.md

@@ -9,8 +9,12 @@ description: Python language gotchas
 
 ```python
 results = [c for raw in data if (c := normalize(raw)) is not None]
-# c IS accessible outside the comprehension! (PEP 572 design)
+# c IS accessible outside the comprehension (PEP 572 design) —
+# but only if the walrus actually ran: with an empty `data`, reading c
+# raises NameError. It runs even for filtered-out elements (the walrus
+# sits in the condition), so c holds the last *evaluated* value, not the
+# last *kept* one.
 # Unlike regular loop variables, := leaks to enclosing scope
 ```
 
-Sonnet confidently says "c is NOT accessible" — this is wrong. The walrus operator in comprehensions intentionally binds in the containing scope.
+The common confident claim "c is NOT accessible outside" is wrong — the walrus operator in comprehensions intentionally binds in the containing scope.

package/templates/skills/math/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: math
-description: Math overflow boundary gotchas
+description: Math gotchas — integer overflow boundaries, cross-runtime float parity (tan/pow ULP drift), FP modulo-wrap pitfalls
 ---
 
 # Math — Verified Gotchas
@@ -10,5 +10,67 @@ description: Math overflow boundary gotchas
 | Type | Last fits | First overflow |
 |------|-----------|----------------|
 | Int64 | C(66, 33) = 7,219,428,434,016,265,740 | C(67, 33) |
+| UInt64 | C(67, 33) = 14,226,520,737,620,288,370 | C(68, 34) |
 
-Sonnet consistently underestimates this boundary (says n=62, correct is n=66).
+Models consistently underestimate this boundary (a common wrong answer is n=62; correct is n=66 for Int64).
+
+**Result vs computation**: the table bounds the RESULT. Intermediate products in the usual `res = res * (n-k+i) / i` loop overflow earlier (the multiply happens before the divide) — the last few safe n need 128-bit intermediates or a divide-first formulation.
+
+## Cross-runtime trig: V8 `Math.tan` ≠ CPython `math.tan` by 1 ULP
+
+When building bit-exact parity between TS/JS and Python implementations of
+the same math, **`tan` is the single biggest offender**. V8 and CPython do
+not share a single implementation (V8 ships its own fdlibm-derived routines;
+CPython calls platform libm), and `tan`'s range reduction produces a
+different LSB from naive `sin(x)/cos(x)` for some angles — which layer is
+responsible varies by platform.
+
+**Fix**: compute `tan(x)` as `sin(x) / cos(x)` in BOTH languages. `sin` and
+`cos` round-tripped bit-identically across the tested runtimes.
+
+| Op | V8 `Math.X` vs CPython `math.X` | Use? |
+|---|---|---|
+| `sin`, `cos` | bit-identical (observed) | yes |
+| `sqrt` | bit-identical (IEEE-754 mandates correctly-rounded) | yes |
+| `tan` | **1 ULP drift possible** | avoid — use `sin/cos` |
+| `**` (pow) | 1-2 ULP drift possible | accept tolerance |
+| `atan`, `atan2`, `exp`, `log` | 1-2 ULP drift possible | accept tolerance |
+
+**Even after sin/cos swap**, `pow(x, y)` (e.g. `step_mult = floor + norm**exp`)
+can still produce 1-ULP-different doubles between V8 and CPython for some
+inputs. If the math identity is preserved (same algorithm, same constants,
+sin/cos for tan), `math.isclose(rel_tol=1e-12, abs_tol=1e-9)` covers ~2 ULP
+at typical magnitudes and is the right tolerance for "bit-exact in spirit".
+
+**Concrete example**: a projectile-apex derivation
+`apexAboveMidline = (range/4) * tan(angleRad)`. V8 emitted
+`tan=0.32130439756415801744`; CPython emitted `tan=0.32130439756415796193`.
+After swapping both to `sin(x)/cos(x)`, both emitted the second value.
+Remaining rare failures (9/1000 seeds) came from `**1.8` in the step
+multiplier — those needed the `isclose` tolerance.
+
+## Modulo-wrap round-trip is NOT identity for in-range floats — never gate "did it wrap?" on FP equality
+
+`wrapped = lo + (((x - lo) % span) + span) % span` for `x` ALREADY in
+`[lo, hi)` returns a value that differs from `x` by ~1 ULP(span) on a large
+fraction of inputs. The `%` ops themselves are exact — `%` is
+truncated-division remainder (C `fmod` semantics), which IEEE 754 requires
+to be exact; note it is NOT the IEEE `remainder()` operation (round-nearest
+quotient), a different op. The error comes from the surrounding `x-lo`,
+`+span`, `lo+m` adds, each of which rounds. Measured: 41–67% of in-range
+values fail `wrapped === x` depending on the window; with `lo` and `x` of
+matching magnitude the subtraction is Sterbenz-exact and the identity HOLDS
+(0/1e6 failures) — so the spurious rate silently depends on runtime state
+(camera position), making it look fine in one regime and fire constantly in
+another.
+
+**Failure mode**: `if (wrapped !== x) onWrap()` as a "teleport happened"
+detector fired the callback ~60 Hz for every entity instead of once per
+recycle — and a simulation harness with the same window shape "validated"
+the degenerate behavior convincingly.
+
+**Right**: detect the wrap by RANGE, then normalize:
+```js
+if (x < lo || x >= hi) { x = lo + (((x - lo) % span) + span) % span; onWrap(); }
+```
+Also skips the modulo (and its FP noise re-write) in the common in-range case.

package/templates/skills/mcp-setup/SKILL.md

@@ -6,9 +6,16 @@ description: MCP server setup and troubleshooting
 ## Rules
 
 1. **NEVER guess package names** → `npm info <name>` to verify before installing
-2. **Validate before adding** → `npm info` → `npx -y <pkg> --help` → `claude mcp add`
+2. **Validate before adding** → `npm info` → `npx -y <pkg> --help` → `claude mcp add`. Caveat: many MCP servers don't implement `--help` and just wait on stdio — wrap validation in `timeout 10 …` so it can't hang.
 3. **Think UX upfront** → headless mode, timeouts, flags — ask user BEFORE installing
-4. **Minimize restarts** → each MCP change = session restart. Get it right first time.
+4. **Restarts**: `/mcp` can reconnect already-registered servers, but registering a NEW server requires a session restart. Get the config right the first time.
+
+## Quick Facts
+
+- Python servers: `claude mcp add <name> -- uvx <pkg>` — uvx launches PyPI packages over stdio, no venv management.
+- Remote servers: `claude mcp add --transport http <name> <url>` (also `--transport sse` for legacy SSE servers).
+- Scopes: `project` scope lives in `.mcp.json` at the repo root (checked in); `local` scope lives in `~/.claude.json` under that project's entry (NOT in the repo); `user` scope is global in `~/.claude.json`.
+- Plugin-bundled servers get tool names `mcp__plugin_<plugin>_<server>__<tool>` — the full name must stay under the 64-char API limit, so keep plugin/server names short.
 
 ## Troubleshooting
 
@@ -16,3 +23,8 @@ description: MCP server setup and troubleshooting
 2. Run command manually to see error
 3. `npm whoami` — fix stale token if needed
 4. `npm info <pkg> deprecated` — check if abandoned
+
+## Browser MCP (playwright/chrome-devtools)
+
+- **"Browser is already in use … use --isolated"** = the persistent Chrome profile (`~/Library/Caches/ms-playwright-mcp/mcp-chrome-*` on macOS, `~/.cache/ms-playwright-mcp/mcp-chrome-*` on Linux) is locked by a stale `SingletonLock` symlink (often pointing at an unrelated regular Chrome pid). The MCP server refuses even after `browser_close`.
+- **Fix without killing the user's Chrome**: if more than one browser MCP server is configured, each has its own profile — switch to the other server rather than `kill`ing the pid the lock points at (it may be the user's real browser). Stay with ONE browser server per session; alternating between two hits the lock again.

package/templates/skills/preferences/SKILL.md

@@ -5,11 +5,11 @@ description: User's general coding preferences
 
 ## User's personal coding preferences
 
-These rules are set by the user through direct feedback.
-They ALWAYS take priority over base skills.
+Rules in this file ALWAYS take priority over base skills.
 
-<!-- Add your preferences here. The sections below are examples — -->
-<!-- customize them to match your coding style. -->
+<!-- Customize this file to match your coding style: the uncommented -->
+<!-- rules below are shipped defaults — keep, edit, or delete them. -->
+<!-- Commented rules are examples to uncomment and adapt. -->
 
 ### Model usage
 
@@ -38,9 +38,9 @@ They ALWAYS take priority over base skills.
 ### Naming
 
 - Private fields (variables) must start with `_` prefix: `_count`, `_items`
+- This applies to instance variables, NOT to methods or constants
+- Public fields do NOT use underscore prefix
 <!-- - Event listener methods: use `Handler` suffix, not `on` prefix -->
-<!-- - This applies to instance variables, NOT to methods or constants -->
-<!-- - Public fields do NOT use underscore prefix -->
 
 ### Comments and documentation
 
@@ -53,10 +53,10 @@ They ALWAYS take priority over base skills.
 <!-- - No curly braces for single-line bodies -->
 <!-- - Combine `for` + `if` into `for (...) if (...) {` — preferred over `if (!cond) continue;` -->
 
-### Error handling
-
-- Never silently swallow invalid state — throw exceptions instead of returning quietly
-
 ### Magic numbers
 
 <!-- - No magic number literals in logic — extract into a named constant -->
+
+### Error handling
+
+- Never silently swallow invalid state — throw exceptions instead of returning quietly

package/templates/skills/skill-manager/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: skill-manager
+description: Create, install, update, optimize skills
+---
+
+## Skill lifecycle manager
+
+This skill is HEAVY. Always run via subagent (Task tool), never in main context.
+
+### Model policy
+
+- Use **Opus** or **Sonnet** for subagents
+- **NEVER use Haiku** — insufficient for quality work
+- Skills are optimized for Opus/Sonnet reasoning capabilities
+
+**Model selection by task:**
+- **OPTIMIZE skills** → Sonnet (filtering/editing, doesn't need deep reasoning)
+- **CREATE skill from research** → Sonnet (research + writing)
+- **Complex code generation** → Opus (when quality is critical)
+
+### ⛔ PROTECTED skills — NEVER modify or overwrite
+
+Skills matching `preferences*` (`preferences/`, `preferences-<lang>/`,
+any other `preferences-*` variant) are user-owned personal rules.
+
+These are ONLY updated when the user gives direct feedback.
+skill-manager must NEVER touch, overwrite, or regenerate them without
+an explicit user request.
+
+### 1. FIND an existing skill
+
+Search order:
+A) Check awesome-agent-skills: https://github.com/VoltAgent/awesome-agent-skills
+B) Check awesome-claude-code: https://github.com/hesreallyhim/awesome-claude-code
+C) Check anthropics/skills: https://github.com/anthropics/skills
+D) Search npm: `npm search claude skill <keyword>`
+E) Search GitHub: `gh search repos "claude skill <keyword>"`
+
+**IMPORTANT:** Subagents don't have access to skills. When launching a research subagent, include these web-reading rules in the prompt:
+
+1. For GitHub repos/issues/PRs → use `gh` CLI, not web fetch
+2. Fetch web pages via Jina Reader: `WebFetch("https://r.jina.ai/<url>", "<precise extraction prompt>")`
+3. If Jina fails → direct `WebFetch` with prompt: "Extract ONLY main article content as clean markdown. Ignore navigation, sidebars, headers, footers, ads."
+4. If page inaccessible → `WebSearch` for mirrors, docs, cached versions
+5. ALWAYS specify exactly what to extract — never "get the page" or "summarize"
+
+### 2. INSTALL an existing skill
+
+```bash
+# From known repos
+npx -y openskills install <owner/repo/skill-name> -g
+
+# Or manually
+# 1. Fetch the SKILL.md content
+# 2. Write to ~/.claude/skills/<skill-name>/SKILL.md
+# 3. Copy any scripts/, references/, assets/ if present
+```
+
+After install, verify:
+- SKILL.md has valid frontmatter (name, description)
+- Description doesn't overlap with existing skills
+- Fits the layered architecture: universal → lang → domain → target
+
+### 3. CREATE a new skill from scratch
+
+Follow Anthropic's skill-creator principles:
+
+A) **Size = f(content)** — can be 10 lines or 500, depends on how much Claude DOESN'T know
+B) **CRITICAL: Don't teach what Claude already knows!**
+C) **When in doubt — EXCLUDE** (easier to add later than to remove)
+D) **Minimal code examples** — only to illustrate a gotcha, not full solutions
+E) **Always add `description` to frontmatter** — max 5-6 words, as short as possible. Without it Claude won't load the skill.
+F) **Do NOT add `disable-model-invocation`** — skills must be callable via Skill() tool. Discovery chain: workflow `think` state → domain mapping → `Skill(name)`.
+G) Use progressive disclosure:
+   - SKILL.md body (<5k words) = loaded when triggered via Skill()
+   - references/ = loaded on demand
+
+### ⚠️ What to include vs exclude in skills
+
+**NEVER include** (Claude already knows this):
+- Basic syntax of mainstream languages
+- Standard library functions that are well-documented
+- Common design patterns (singleton, factory, observer)
+- General programming principles (DRY, SOLID)
+- Popular framework basics (React, ASP.NET, Django)
+- **Well-known patterns with full examples** (multi-stage Docker builds, async/await)
+- **Obvious best practices** (use .gitignore, validate input)
+- **Standard CLI commands** (docker run, git commit, npm install)
+
+**ALWAYS include** (Claude needs this):
+- **Gotchas and pitfalls** — things Claude commonly gets wrong
+- **Subtle differences** — from similar languages/frameworks
+- **Non-obvious conventions** — that differ from common patterns
+- **Version-specific changes** — recent updates Claude may not know
+- **Integration quirks** — how things work together in practice
+- **User's preferences** — always in preferences-* skills
+- **Niche topics** — obscure APIs, legacy systems, specialized domains
+
+**Process for creating a lang-* or domain-* skill:**
+
+1. Start with EMPTY file
+2. Research web for "gotchas", "common mistakes", "pitfalls" in this domain
+3. For each finding — two-model filter (Opus + Sonnet):
+   - Both models know it → SKIP (water)
+   - At least one doesn't know → INCLUDE
+4. Specific numbers/boundaries → always verify by computation, record exact values
+5. If nothing passes the filter → maybe this skill isn't needed
+
+**Two-model consensus** (mirrors water-removal):
+- Remove what BOTH models know
+- Add what at LEAST ONE model doesn't know
+
+**Gotcha vs Pattern — examples:**
+```
+✗ EXCLUDE: "Use multi-stage builds to reduce image size"
+  (well-known pattern, Claude knows this)
+
+✓ INCLUDE: "COPY --from=0 uses stage INDEX, not name — breaks if stages reordered"
+  (gotcha, easy to miss)
+
+✗ EXCLUDE: "Use async/await for asynchronous code"
+  (basic syntax)
+
+✓ INCLUDE: "ConfigureAwait(false) in library code — otherwise deadlock in UI"
+  (subtle gotcha, context-dependent)
+```
+
+Structure:
+```
+~/.claude/skills/<skill-name>/
+├── SKILL.md           # Required: frontmatter + instructions
+├── references/        # Optional: detailed docs, schemas
+├── scripts/           # Optional: executable helpers
+└── assets/            # Optional: templates, samples
+```
+
+Naming for layered architecture:
+- Universal: `code-writing`, `architecture`, `testing`, `refactoring`
+- Language: `lang-csharp`, `lang-haxe`, `lang-python`
+- Domain: `domain-unity`, `domain-dotnet`, `domain-gamedev`
+- Target: `target-hashlink`, `target-aspnet`, `target-webgl`
+
+### 4. CONVERT documentation into a skill
+
+For turning language/framework docs into a skill:
+
+A) Fetch documentation using web-reading chain
+B) Extract:
+   - Core idioms and conventions
+   - Common patterns and anti-patterns
+   - API quick reference (signatures, not full docs)
+   - Gotchas and common mistakes
+C) Structure as SKILL.md — focus on what Claude wouldn't know
+D) Move detailed API references to references/ directory
+E) Write precise description for auto-invocation
+
+### 5. ENRICH skill from observed error
+
+Triggered by reflection when Claude makes a verifiable mistake.
+
+1. Identify the error and the skill it belongs to
+2. Research the correct answer: code verification → web docs → web search
+3. Verify the correct answer by running code (if possible)
+4. Add ONLY the verified correction to the existing skill
+5. Format: show the wrong thing and the right thing with exact values
+
+Example flow: Claude writes `Fib(46) overflows Int32` → verification shows Fib(46) fits,
+Fib(47) overflows → add verified table to math skill with exact numbers.
+
+### 6. UPDATE an existing skill (manual)
+
+```bash
+# Via openskills (if installed from repo)
+npx -y openskills update <skill-name>
+
+# Or manually
+# 1. Read current ~/.claude/skills/<skill-name>/SKILL.md
+# 2. Identify what's missing or wrong
+# 3. Edit with improvements
+# 4. Verify description still fits
+```
+
+### 7. LIST and AUDIT current skills
+
+```bash
+ls ~/.claude/skills/
+```
+
+Check for:
+- Overlapping descriptions between skills
+- Skills that are too large (>500 lines)
+- Missing skills for languages/domains being used
+- Outdated information
+
+### 8. OPTIMIZE skills (on model version change)
+
+When Claude version changes (e.g., 4.5 → 5.0), run optimization:
+
+**Trigger:** User says "optimize skills" or new model version detected.
+
+**Process for each skill:**
+
+1. Read the skill content
+2. For each piece of information, ask:
+   - "Does the NEW model already know this?" → REMOVE if yes
+   - "Is this a gotcha/pitfall that's still relevant?" → KEEP
+   - "Is this user's preference?" → NEVER TOUCH (preferences-*)
+   - "Has this API/convention changed?" → UPDATE from fresh research
+3. Re-test: does the skill still add value?
+4. If skill becomes nearly empty → consider deleting it
+
+**What to keep regardless of model version:**
+- User preferences (preferences-*)
+- Behavioral/meta skills (reflection)
+- Infrastructure skills (web-reading, mcp-setup)
+- Recent version-specific changes (last 6-12 months)
+- Niche domains (ANE, Re-ID pipelines)
+
+**What to aggressively prune:**
+- Basic syntax of mainstream languages
+- Well-documented standard library functions
+- General programming principles
+- Popular framework basics
+
+**Deduplicate with preferences:**
+During optimization, check preferences-* skills for this language/domain.
+If a rule exists in preferences-*, REMOVE it from the base skill.
+User preferences always win — no need to duplicate.
+
+Example: if preferences-haxe says "use final class", remove any mention
+of final class conventions from lang-haxe.
+
+**Log optimizations:**
+After optimization, note in MEMORY.md:
+- Date optimized
+- Model version optimized for
+- What was removed/kept/updated
+
+### 9. UPDATE selector domain mappings after creating new skills
+
+**MANDATORY:** After creating or installing any new skill, update the domain mapping
+in `~/.claude/skills/coding-skill-selector/SKILL.md` — one place.
+
+Add the new skill to the appropriate section (by extension or by domain), e.g.:
+```
+- NewDomain → `Skill("domain-newdomain")`
+```
+
+**This single skill is loaded at the skill-gate states of all code-related workflows (coding, debugging, bug-fix, code-review, etc.).**
+
+### Language rule
+
+All skills MUST be written in English only. Never mix languages in skill files.
+
+### Validation checklist
+
+Before finishing any skill operation:
+- [ ] Frontmatter has `name` + short `description` (no disable-model-invocation)
+- [ ] Name is hyphen-case, max 64 chars
+- [ ] SKILL.md ≤500 lines (size driven by content, not arbitrary target)
+- [ ] Follows layered architecture (universal/lang/domain/target)
+- [ ] Only gotchas/pitfalls — no basic patterns Claude already knows
+- [ ] If skill is nearly empty → maybe it's not needed
+- [ ] **selector domain mapping updated** (coding-skill-selector skill)

package/templates/skills/target-openfl-native/SKILL.md

@@ -129,8 +129,10 @@ while (!_worker.isStopped() && waited < TIMEOUT_MS) {
     Sys.sleep(0.1);
     waited += 100;
 }
-if (waited < TIMEOUT_MS) {
-    // Thread stopped cleanly — safe to close resources
+if (_worker.isStopped()) {
+    // Thread stopped cleanly — safe to close resources.
+    // Re-check the flag, NOT the timer: the worker may have stopped
+    // during the final sleep, right as the timeout expired.
     try db.close() catch (e:Dynamic) {};
 }
 // Always null out regardless
@@ -143,11 +145,11 @@ _worker = null;
 
 ```haxe
 // WRONG — parent field nulled but still in __children → main thread renders it
-pitchAreaGroup.parent = null;
+child.parent = null;
 
 // RIGHT — remove from __children, then null parent
-@:privateAccess parent.__children.remove(pitchAreaGroup);
-pitchAreaGroup.parent = null;
+@:privateAccess parent.__children.remove(child);
+child.parent = null;
 ```
 
 To restore, save the child index before removing and re-insert at the same position:
@@ -169,6 +171,39 @@ child.parent = savedParent;
 
 `Sys.exit()` calls C `exit()`. In worker threads, stdout buffer may not flush. Always call `Sys.stdout().flush()` before `Sys.exit()`.
 
+### Sys.exit() races hxcpp GC mutex destruction → `mutex lock failed: Invalid argument`
+
+`Sys.exit()` → libc `exit()` → runs C++ static destructors, including hxcpp's GC mutexes (`sThreadPoolLock` in `hx::gc::Immix.cpp`, `g_threadInfoMutex` in `hx::Thread.cpp`). The GC worker thread is NOT stopped by `exit()`. Its next `pthread_mutex_lock` on a now-destroyed mutex returns EINVAL → libc++abi terminates with `mutex lock failed: Invalid argument`. Manifests differently per platform: Linux shows `terminate ... std::system_error ... Invalid argument`, Windows is silent or AV, macOS crashes at unit test exit.
+
+Fix: after cooperative cleanup, skip C++ static destructors by calling `_Exit` (see below).
+
+### `_exit` from `<unistd.h>` is NOT available; use `_Exit` from `<cstdlib>`
+
+hxcpp does NOT auto-include `<unistd.h>`. `untyped __cpp__("::_exit({0})", code)` fails with `error: no type named '_exit' in the global namespace`.
+
+Use C99 `_Exit` (capital E) from `<cstdlib>` — skips C++ static destructors and atexit handlers, identical to `_exit` in effect, portable across Darwin/Linux/Windows MSVC.
+
+```haxe
+// WRONG — <unistd.h> not included by hxcpp; compile error
+untyped __cpp__("::_exit({0})", code);
+
+// RIGHT — <cstdlib> is safe; _Exit skips static destructors
+@:cppFileCode("#include <cstdlib>")
+final class CleanExit {
+    public static function exit(code:Int):Void {
+        try Sys.stdout().flush() catch (_:Exception) {}  // see "doesn't flush stdout" above
+        try Sys.stderr().flush() catch (_:Exception) {}
+        #if cpp
+        untyped __cpp__("std::_Exit({0})", code);
+        #else
+        Sys.exit(code);
+        #end
+    }
+}
+```
+
+**Warning**: `_Exit` skips ALL atexit handlers. Any pending writes (DB flushes, file saves) are lost. Only call after cooperative cleanup. Keep this as a small shared utility class.
+
 ## Extern Patterns (@:native)
 
 ### Pointer suffix for heap-allocated types
@@ -225,7 +260,7 @@ Including `<OpenGLES/EAGL.h>` or any header that pulls in `Foundation.h` inside
     #include <objc/runtime.h>
     #include <objc/message.h>
 
-    static void* tm_get_eagl_context() {
+    static void* get_eagl_context() {
         Class cls = objc_getClass("EAGLContext");
         SEL sel = sel_registerName("currentContext");
         return ((void* (*)(id, SEL))objc_msgSend)((id)cls, sel);
@@ -279,25 +314,25 @@ No leading slashes in asset paths — `"/manifest/default.json"` crashes on some
 
 **GlowFilter on Label/Sprite container** — apply to the parent container (Label, Sprite), NOT to TextField directly. `label.filters = [new GlowFilter(...)]` works. `textField.filters` inside a Label wrapper does NOT produce visible results.
 
-**BitmapData.draw() does NOT capture filters** — `bmd.draw(stage)` uses the software renderer and skips GPU filters. Use `window.readPixels()` instead — reads from the GPU framebuffer and captures everything including filters. Debug bridge already uses readPixels with fallback to draw.
+**BitmapData.draw() does NOT capture filters** — `bmd.draw(stage)` uses the software renderer and skips GPU filters. Use `window.readPixels()` instead — reads from the GPU framebuffer and captures everything including filters. Screenshot tooling (e.g. a debug bridge) should use readPixels with draw() as fallback.
 
 **Search codebase first** — before implementing text outlines, shadows, or effects, grep for existing `GlowFilter`/`DropShadowFilter` usage in the project. Likely already solved with correct params.
 
 **`DisplayObject.filters != null` forces `cacheAsBitmap = true`** — the getter is `return (__filters == null ? __cacheAsBitmap : true)`. Any non-null filters array (even a filter with alpha=0 or zero-radius) causes the object to render through the intermediate bitmap-cache path. Symptoms:
 
 - Setting `obj.cacheAsBitmap = false` has NO effect when `filters != null` — the getter still returns `true`.
-- At high render scales (video export, offscreen `BitmapData.draw` with large matrix), the intermediate cache bitmap can be sized wrong for the target, visually clipping the right/bottom of content (e.g. missing right post, missing background geometry).
+- At high render scales (video export, offscreen `BitmapData.draw` with large matrix), the intermediate cache bitmap can be sized wrong for the target, visually clipping the right/bottom of content (elements near those edges silently disappear from the output).
 
 ```haxe
 // WRONG — unselected state keeps a zero-alpha filter "to avoid allocations"
-override function set_isSelected(value:Bool):Bool {
+override private function set_isSelected(value:Bool):Bool {
     final alpha:Float = value ? 1 : 0;
     obj.filters = [new GlowFilter(color, alpha, 4, 4, 1)];  // still forces cacheAsBitmap
     return isSelected = value;
 }
 
 // RIGHT — null out filters when not needed
-override function set_isSelected(value:Bool):Bool {
+override private function set_isSelected(value:Bool):Bool {
     obj.filters = value ? [new GlowFilter(color, 1, 4, 4, 1)] : null;
     return isSelected = value;
 }
@@ -343,7 +378,7 @@ bytes.blit(botOff, tmp, 0, rowStride);        // tmp → bottom
 
 ### BitmapData.draw pixelRatio vs cache bitmaps (text blur on Windows)
 
-`BitmapData.draw()` sets `renderer.__pixelRatio = window.scale`. TextFields with filters (GlowFilter, DropShadowFilter) go through `__updateCacheBitmap` which creates the cache bitmap at `pixelRatio` resolution. On Windows (`window.scale=1`), cache bitmaps are 1x — if the draw matrix scales up (e.g. video export batchMatrix ~2x), the 1x cache is upscaled → blurry text.
+`BitmapData.draw()` sets `renderer.__pixelRatio = window.scale`. TextFields with filters (GlowFilter, DropShadowFilter) go through `__updateCacheBitmap` which creates the cache bitmap at `pixelRatio` resolution. On Windows (`window.scale=1`), cache bitmaps are 1x — if the draw matrix scales up (e.g. a ~2x video-export draw matrix), the 1x cache is upscaled → blurry text.
 
 **Fix**: set `pixelRatio = max(window.scale, transform_scale)` in `BitmapData.draw()` so cache bitmaps are rasterized at the final output resolution. This fixes BOTH code paths — text with filters (cache bitmap) and text without filters (Context3DTextField.render).
 
@@ -391,7 +426,7 @@ graphics.endFill();
 shape.x = containerWidth - FADE_WIDTH;  // gradient at edge, solid extends past it
 ```
 
-Key: solid rect goes PAST `containerWidth`, not before it. Parent mask clips the visual excess, but the fill covers any children that overshoot the boundary (e.g. scrollbar offset by `barPad`). Verify with `display_find` — check child positions and widths to confirm the cover extends past all children.
+Key: solid rect goes PAST `containerWidth`, not before it. Parent mask clips the visual excess, but the fill covers any children that overshoot the boundary (e.g. scrollbar offset by `barPad`). Verify by inspecting the display tree (debug-bridge query, runtime trace) — check child positions and widths to confirm the cover extends past all children.
 
 ## Actuate (Tween Library)
 
@@ -442,7 +477,7 @@ OpenFL provides utility methods that are easy to miss. Use them instead of writi
 | `HXCPP_STACK_LINE` | Line numbers (implies above) | Medium |
 | `-debug` | All above + no optimization | ~80% |
 
-**Crash investigation builds**: When reproducing a crash via debug bridge, always add `-DHXCPP_CHECK_POINTER` to the build flags. Without it, a Null Object Reference is a silent segfault with no stack trace — useless for diagnosis. `-debug` includes it automatically, but if already building with `-debug`, you're covered.
+**Crash investigation builds**: When building a binary to reproduce a crash, always add `-DHXCPP_CHECK_POINTER` to the build flags. Without it, a Null Object Reference is a silent segfault with no stack trace — useless for diagnosis. `-debug` includes it automatically, but if already building with `-debug`, you're covered.
 
 **Null function pointer = hard crash**: `var f:Void->Void = null; f();` → C++ NULL dereference, not catchable. Check before calling.
 
@@ -515,8 +550,8 @@ this.stage.addEventListener(Event.RESIZE, handler);  // if 'this' is a DisplayOb
 Logical coords → `stage.__onMouse()` requires display-matrix input space, NOT stage coordinates:
 
 ```haxe
-// logical (1080×670) → stage global → display input
-final globalPoint:Point = sceneLayer.localToGlobal(new Point(logicalX, logicalY));
+// logical (app coordinate space) → stage global → display input
+final globalPoint:Point = contentRoot.localToGlobal(new Point(logicalX, logicalY));
 final inputPoint:Point = stage.__displayMatrix.transformPoint(globalPoint);
 stage.__onMouse(MouseEvent.MOUSE_DOWN, inputPoint.x, inputPoint.y, 0);
 ```
@@ -531,9 +566,9 @@ Display list hit-test order: **highest index first** (front-to-back). If a trans
 
 ### Scroll events bypass OS natural-scrolling inversion
 
-Real scroll events: OS/SDL applies natural scrolling → Lime → OpenFL. App compensates via `ScrollContainer.inverted` flag.
+Real scroll events: OS/SDL applies natural scrolling → Lime → OpenFL. Apps typically compensate with their own inversion flag on the scroll component.
 
-Synthetic `stage.__onMouseWheel(deltaX, deltaY, mode)` bypasses OS/SDL, so the app's compensation causes **double inversion**. Fix: negate delta when `ScrollContainer.inverted` is true before passing to `__onMouseWheel`.
+Synthetic `stage.__onMouseWheel(deltaX, deltaY, mode)` bypasses OS/SDL, so the app's compensation causes **double inversion**. Fix: when the app's inversion flag is active, negate the delta before passing it to `__onMouseWheel`.
 
 ### __onMouseWheel needs __mouseX/Y set first
 

package/templates/skills/target-openfl-native/references/build-and-versions.md

@@ -25,10 +25,13 @@
 
 ## Cross-compilation
 
-| From → To | Flag |
-|-----------|------|
-| macOS → Linux | `-cpp` (Homebrew cross-toolchains) |
-| Any → Windows | `-mingw` |
+hxcpp selects the toolchain via defines (`-D ...`). Haxe's `-cpp <dir>` only sets the C++ output directory — it is not a cross-compilation flag.
+
+| From → To | Define |
+|-----------|--------|
+| macOS → Linux | `-D linux` (needs a Linux cross-toolchain, e.g. via Homebrew) |
+| Linux → Windows | `-D windows` (selects the MinGW-w64 cross toolchain) |
+| Windows: MSVC → MinGW | `-D mingw` |
 
 ## CI/CD gotchas