claude-mcp-workflow 0.1.8 → 0.1.9

package/templates/skills/ci-github-actions/SKILL.md

@@ -18,14 +18,14 @@ description: GitHub Actions workflow gotchas
 The action resolves the most recent tag **reachable from the current commit** via git history. With the default `fetch-depth: 1`, no tags are reachable — the action returns empty or stale results.
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v7
   with:
     fetch-depth: 0  # required for tag resolution
 ```
 
 Same applies to `git describe`, `git log --follow`, `gitversion`, and any changelog generator that walks commit history.
 
-## `actions/checkout@v4` Default Fetches Only 1 Commit
+## `actions/checkout` Default Fetches Only 1 Commit (v4+)
 
 Unless `fetch-depth: 0` (full history) or `fetch-depth: N` is set, you get a shallow clone with depth 1. Breaks: tag lookup, `git log`-based changelogs, `git blame`, branch comparison diffs.
 
@@ -53,10 +53,12 @@ deploy:
 # RIGHT — run regardless, check status explicitly
 deploy:
   needs: [build]
-  if: always() && needs.build.result == 'success'
+  if: ${{ !cancelled() && needs.build.result == 'success' }}
   steps: ...
 ```
 
+Prefer `!cancelled()` over `always()`: `always()` forces the job to run even when the workflow run is being cancelled; `!cancelled()` lifts the "dependency failed/skipped" gate but still respects cancellation. (The `${{ }}` is required here — a bare `if:` starting with `!` is invalid YAML.)
+
 ## `$GITHUB_ENV` Changes Are Not Visible in the Same Step
 
 `echo "X=value" >> $GITHUB_ENV` exports `X` for all **subsequent** steps. The current step cannot read it.
@@ -99,46 +101,60 @@ jobs:
   test:
     continue-on-error: true   # whole matrix ignores failures
 
-# Matrix-level — only the flagged cell continues, others still gate the job
-strategy:
-  matrix:
-    os: [ubuntu, windows]
-  fail-fast: false
+# Cell-level — only the flagged cell continues, others still gate the job
 jobs:
   test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu, windows]
     continue-on-error: ${{ matrix.os == 'windows' }}  # only windows cell is optional
 ```
 
+Note `strategy:` lives under `jobs.<job>` — it is not a top-level workflow key.
+
 `fail-fast: false` (strategy level) keeps sibling cells running after one fails. `continue-on-error: true` (job level) prevents the job from being marked failed. They're orthogonal.
 
-## Artifact Names Must Be Unique Within a Run (actions/upload-artifact@v4)
+## Artifact Names Must Be Unique Within a Run (actions/upload-artifact v4+)
 
-v4 dropped the `overwrite` default — uploading two artifacts with the same name in one workflow run is an error, not a silent overwrite.
+v4 made artifacts immutable — uploading two artifacts with the same name in one workflow run is an error (v3 silently merged files into one artifact). Since v4.4 an explicit `overwrite: true` input deletes and replaces the existing artifact; the default is still an error.
 
 ```yaml
 # WRONG — both matrix cells upload "test-results", second one errors
-- uses: actions/upload-artifact@v4
+- uses: actions/upload-artifact@v7
   with:
     name: test-results
 
 # RIGHT — include matrix dimension in the name
-- uses: actions/upload-artifact@v4
+- uses: actions/upload-artifact@v7
   with:
     name: test-results-${{ matrix.os }}
 ```
 
-## `if:` Expressions Use `==` Not `===`, and Strings Are Case-Sensitive
+## `if:` Expressions: Single Quotes Only, Comparison Is Case-INsensitive
 
 ```yaml
-# WRONG — this never matches
-if: github.event_name == "Push"
+# WRONG — double quotes are a validation error in expressions
+if: github.event_name == "push"
 
 # RIGHT
 if: github.event_name == 'push'
 ```
 
-`if:` expressions do NOT require `${{ }}` wrapping (they're evaluated as expressions already). Adding `${{ }}` works but is redundant.
+String literals in expressions must use single quotes — double quotes fail workflow validation. String comparison with `==` ignores case (`'Push' == 'push'` is true). The operator is `==`; there is no `===`.
+
+`if:` expressions do NOT require `${{ }}` wrapping (they're evaluated as expressions already). Adding `${{ }}` works but is redundant — except when the expression starts with `!` (reserved in YAML), e.g. `if: ${{ !cancelled() }}`.
+
+## `env:` Does Not Propagate Into Reusable Workflow Calls (`jobs.<job>.uses`)
+
+A reusable workflow is called at the JOB level (`jobs.<job>.uses`), not as a step. Environment variables set at workflow or job level are available to `run:` steps but are NOT passed into the called reusable workflow. Pass values explicitly via `with:` inputs or `secrets:` instead.
+
+## Default Community Health Files (FUNDING.yml, CODEOWNERS, ISSUE_TEMPLATE) Load ONLY From a Repo Named `.github`
+
+Account-wide defaults for community health files come **only** from a public repo named literally `.github` (e.g. `owner/.github`), in its root or a `.github`/`docs` folder. A repo's own file overrides the default.
+
+**Wrong:** Putting `FUNDING.yml` in the username/profile repo (`owner/owner`, the one with the profile README) expecting it to apply org-wide — it does NOT. It only affects that single repo.
 
-## `env:` at Job Level Is Not Inherited by `uses:` (Reusable Workflow) Steps
+**Right:** Create `owner/.github` (must be public) → its `FUNDING.yml` gives every repo without its own a Sponsor button.
 
-Environment variables set at job level are available to `run:` steps but NOT passed into called reusable workflows (`jobs.<job>.uses`). Pass them explicitly via `with:` inputs or `secrets:` instead.
+`FUNDING.yml` keys are platform-specific usernames, not URLs: `buy_me_a_coffee: <user>`, `patreon: <user>`. There is **no** `paypal:` key — PayPal goes under `custom: ['https://paypal.me/<user>']`.

package/templates/skills/claude-code-config/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: claude-code-config
+description: Claude Code configuration gotchas — permission rule syntax and evaluation order, settings hierarchy, plugin install scopes, hook behavior
 ---
 
 # Claude Code Configuration Gotchas
@@ -14,9 +15,11 @@ name: claude-code-config
 **Common mistake**: Writing `Read(/tmp/**)` when you mean absolute path. Correct: `Read(//tmp/**)`.
 
 **Pattern format must match tool signature**:
-- Correct: `Read(//tmp/**)`, `Bash(npm run *)`
+- Correct: `Read(//tmp/**)`, `Bash(npm run:*)`
 - Wrong: `Read(file_path://tmp/**)` — tool name only, no parameter labels
 
+**Bash rules use `:*` for prefix matching**: `Bash(npm run:*)` matches any command starting with `npm run `. `Bash(npm run *)` (space-star) is NOT the prefix syntax and matches unreliably.
+
 ## Wildcard Matching
 
 **Recursive vs Single Level**:
@@ -29,8 +32,8 @@ name: claude-code-config
 
 **Deny always wins**:
 1. Deny rules checked first (block regardless of anything else)
-2. Allow rules checked second (permit if matched)
-3. Ask rules checked last (prompt user)
+2. Ask rules checked second (prompt user if matched)
+3. Allow rules checked last (permit if matched)
 
 **First match wins** within each category.
 
@@ -48,12 +51,8 @@ name: claude-code-config
 
 ## Known Bugs (as of 2026)
 
-**Deny rules not enforced**: Multiple reported issues (GH #13785, #6631, #4467, #6699) where deny patterns in settings.json are ignored. Tool still gets access despite explicit deny.
-
 **Allow rules ignored**: Issue #18160 reports global allow permissions being ignored, requiring manual approval despite being in allowlist.
 
-**Wildcard pattern bugs**: `Bash(command *)` patterns may fail to match commands with flags or tilde expansion.
-
 ## Domain-Specific Rules
 
 **WebFetch requires domain syntax**:
@@ -64,9 +63,7 @@ name: claude-code-config
 
 **Overly broad wildcards**: Starting with `Bash(*)` or `Read(**)` creates security holes. Be specific.
 
-**Forgetting .gitignore**: By default, Claude respects `.gitignore`. If files missing from suggestions, check ignore rules or set `respectGitignore: false`.
-
-**Environment variables in Bash**: Don't persist between commands. Use `CLAUDE_ENV_FILE` or hooks instead.
+**Environment variables in Bash**: Don't persist between commands. Use the `env` map in settings.json or hooks instead.
 
 **Testing permissions**: Use Shift+Tab to switch permission modes mid-session without editing files.
 
@@ -76,16 +73,16 @@ name: claude-code-config
 {
   "permissions": {
     "allow": [
-      "Read(./.env)",              // relative: .env in settings file dir
+      "Read(./config.json)",       // relative: config.json in settings file dir
       "Read(//tmp/**)",            // absolute: all files in /tmp
       "Read(~/.config/**)",        // home: all files in ~/.config
-      "Read(**/.env)",             // recursive: .env anywhere in subtree
-      "Bash(npm run *)",           // command prefix matching
+      "Read(**/config.json)",      // recursive: config.json anywhere in subtree
+      "Bash(npm run:*)",           // command prefix matching (:* suffix)
       "WebFetch(domain:docs.anthropic.com)"  // domain-specific
     ],
     "deny": [
       "Read(**/secrets/**)",       // block entire directory tree
-      "Bash(rm *)"                 // block dangerous commands
+      "Bash(rm:*)"                 // block dangerous commands
     ]
   }
 }
@@ -94,14 +91,14 @@ name: claude-code-config
 ## Debugging Permission Issues
 
 1. Check hierarchy: local > project > user > enterprise
-2. Check deny rules first (they always win)
+2. Check rule order: deny → ask → allow (deny always wins)
 3. Test pattern manually: Does it match the exact tool signature shown in prompt?
-4. Check for known bugs (deny rules may be ignored)
+4. Check for known bugs (allow rules may be ignored — #18160)
 5. Use `claude mcp list` to verify MCP server status if permission involves MCP tool
 
 ## Plugin Install Scope
 
-`claude plugins install <pkg>@<marketplace>` takes `-s, --scope <user|project|local>` (default: `user`).
+`claude plugin install <pkg>@<marketplace>` (singular `plugin`, not `plugins`) takes `-s, --scope <user|project|local>` (default: `user`).
 
 - `user` — global, ~/.claude/plugins/installed_plugins.json with `"scope": "user"`
 - `project` — must run from within the target project dir; registry entry gets `"scope": "project"` + `"projectPath": "<cwd>"`. Plugin activates only when Claude Code runs inside that dir
@@ -109,14 +106,39 @@ name: claude-code-config
 
 Swap scope = uninstall + reinstall (no in-place conversion):
 ```bash
-claude plugins uninstall <pkg>@<mkt> --scope user
-cd /path/to/project && claude plugins install <pkg>@<mkt> --scope project
+claude plugin uninstall <pkg>@<mkt> --scope user
+cd /path/to/project && claude plugin install <pkg>@<mkt> --scope project
 ```
 
 All scopes share the same `~/.claude/plugins/cache/` payload — only the registry entry differs.
 
+## Stop Hook Fires Per Turn, Not on Process Exit
+
+**Wrong assumption**: `Stop` hook = "CLI process is shutting down / session ending".
+**Correct**: `Stop` fires **each time the main agent finishes responding** (end of every turn). One CLI process lifetime can trigger it dozens of times. Docs: *"when Claude finishes responding"* — [docs.claude.com/en/docs/claude-code/hooks](https://docs.claude.com/en/docs/claude-code/hooks).
+
+`SubagentStop` fires when a subagent (Task tool) finishes — separate from the main agent's Stop.
+
+**Practical implication**: Any state registered on `UserPromptSubmit` and released on `Stop` churns every turn. For per-process state (e.g. a background daemon, a lock file, an IPC socket) key by **CLI PID** — `session_id` is wrong because it also changes on `/clear`, `/compact`, or resume within the same process.
+
+```
+UserPromptSubmit → fires before each user turn
+Stop             → fires after each assistant response (not at exit)
+SubagentStop     → fires when a Task-tool subagent completes
+PostToolUse      → fires after each individual tool call within a turn
+```
+
 ## npx Argument Re-parsing Under PreToolUse Hooks
 
 PreToolUse Bash hooks that rewrite commands can mis-parse `npx -y <pkg>@latest <subcmd>`, with `<pkg>@latest` landing as an **npm** subcommand, producing `Unknown command: "<pkg>@latest"`.
 
 Workaround: invoke through a wrapper that bypasses the rewriter (e.g. an explicit `proxy` subcommand of the hook tool, or call the binary directly without `npx -y`). The same `npx` call may succeed via workflow-engine exec while failing via Bash tool — the difference is whether the hook intercepts.
+
+## Multiple Hook Entries for the Same Event Run in Parallel
+
+**Wrong assumption**: Two `PreToolUse` entries in `hooks.json` run in declaration order — first entry first, second entry second.
+**Correct**: All entries for the same event fire **simultaneously**. Declaration order is not execution order.
+
+**Race-condition trap**: If entry A writes a marker file and entry B deletes it, the outcome depends on timing, not position. A fast B (~0 ms) completes before a slow A (~30–50 ms), so A's delete wins even when B is declared last. Symptom: your write appears to have no effect.
+
+**Fix**: One hook entry per event. Inspect stdin JSON inside that single script/command and branch on `tool_name` or other fields to dispatch logic. This guarantees deterministic ordering because it's a single process.

package/templates/skills/cleanup/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: cleanup
+description: Clean .claude directory data
+---
+
+## .claude directory cleanup
+
+Run steps in order. **Ask user confirmation before each step.**
+
+### Step 1: Temp data (always safe)
+
+Delete contents of (keep directories themselves):
+- `~/.claude/debug/` — session debug logs
+- `~/.claude/shell-snapshots/` — zsh state snapshots
+- `~/.claude/todos/` — task lists from past sessions
+- `~/.claude/plans/` — plan files from past sessions
+
+Show size before/after.
+
+### Step 2: Project session logs
+
+For each project in `~/.claude/projects/`:
+- **DELETE**: `*.jsonl` files (conversation logs), `UUID/` directories (session caches), `agent-*.jsonl` (subagent logs)
+- **KEEP**: `memory/` directory, `CLAUDE.md` file
+
+⚠️ This breaks `/resume` for old sessions. Warn user.
+
+Show size before/after.
+
+### Step 3: Empty project directories
+
+After step 2, list projects that have no remaining files (no memory/, no CLAUDE.md).
+Offer to remove them — they recreate automatically when Claude Code runs in that project.
+
+### Step 4: Memory audit
+
+For each remaining `memory/MEMORY.md`:
+1. Read its contents
+2. Check each entry against existing skills — is it already covered?
+3. Check if Claude already knows this without any skill
+4. Present table to user:
+
+| Entry | Duplicates? | Verdict |
+|---|---|---|
+| ... | skill X / common knowledge / project-specific | delete / keep |
+
+Only modify after user approval.
+
+### Other cleanable files
+
+Also check and report sizes of:
+- `~/.claude/history.jsonl` — conversation history (can be large)
+- `~/.claude/file-history/` — file change history
+- `~/.claude/paste-cache/` — clipboard cache
+- `~/.claude/tasks/` — task data
+
+These are less critical. Mention sizes, let user decide.

package/templates/skills/coding-skill-selector/SKILL.md

@@ -21,7 +21,7 @@ Load coding skills for files/context in this task.
 
 3. By domain (detect from imports, paths, or task description):
    - YOLO / object detection → `Skill("domain-yolo")`
-   - Pixi.js / pixi.js imports → `Skill("domain-pixi")`
+   - Pixi.js (imports from `pixi.js`, PIXI globals) → `Skill("domain-pixi")`
    - Person re-identification (ReID) → `Skill("domain-reid")`
    - Game dev (physics, precision, camera, sprites) → `Skill("domain-gamedev")`
    - OpenFL / hxcpp native target → `Skill("target-openfl-native")`
@@ -35,6 +35,7 @@ Load coding skills for files/context in this task.
    - Claude Code settings.json / hooks / permissions / plugin config → `Skill("claude-code-config")`
    - Workflow YAML in templates/ or .claude/workflows/ → `Skill("workflow-authoring")`
    - Fetching web docs / external content → `Skill("web-reading")`
+   - Verifying a web/canvas app via Playwright or a browser MCP (screenshots, captures, perf) → `Skill("browser-verify")`
 
 5. If 3+ independent files or parallel work → `Skill("task-delegation")`
 

package/templates/skills/debug-bridge-scaffold/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: debug-bridge-scaffold
+description: Meta-skill for creating debug bridges for new technologies
+---
+
+# Debug Bridge Scaffold
+
+## When to Use
+
+When you need runtime inspection of an application built with a technology that has no existing debug bridge.
+
+## Step 1: Check Existing Solutions First
+
+Before building a custom bridge, check if a standard tool already works:
+
+| Technology | Existing Solution |
+|-----------|-------------------|
+| Web/Electron/browser apps | Playwright MCP, browser DevTools |
+| Native apps with standard UI toolkit | Accessibility API MCP |
+| Any app with visible UI | Computer Use (screenshot + click) |
+| OpenFL/hxcpp | `debug-bridge-openfl` skill (already exists) |
+
+**If an existing solution covers your needs — use it. Don't build a bridge.**
+
+## Step 2: Build a Custom Bridge
+
+If no existing tool works, create an HTTP bridge following this pattern:
+
+### Architecture
+
+```
+[Background Thread] HTTP Server (127.0.0.1:PORT)
+    ↓ accept()
+[Worker Thread] Parse request → dispatch to main thread
+    ↓ runOnMainThread(fn)
+[Main Thread] Execute handler → return result
+    ↑ result via Lock/Mutex
+[Worker Thread] Send HTTP response
+```
+
+### Required Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/ping` | GET | Health check |
+| `/screenshot` | GET | Capture visual state → save to /tmp → return path |
+| `/shutdown` | POST | Graceful exit |
+
+### Framework-Specific Endpoints
+
+Add endpoints relevant to the technology:
+- **UI frameworks**: display tree, component inspection, event simulation
+- **Game engines**: scene graph, entity list, physics state
+- **Servers**: request log, connection pool, cache state
+
+### Implementation Checklist
+
+1. HTTP server on background thread (127.0.0.1 only — no external access)
+2. Main-thread dispatch for all UI/rendering operations
+3. JSON envelope: `{"ok": true, "data": ...}` / `{"ok": false, "error": "..."}`
+4. Conditional compilation (only in debug builds)
+5. Graceful shutdown (close socket, flush stdout, exit)
+
+## Step 3: Create a Tech-Specific Skill
+
+After building the bridge, create `~/.claude/skills/debug-bridge-<tech>/SKILL.md` with:
+
+1. Build command with the debug flag
+2. Binary path pattern
+3. All endpoints with parameters and example responses
+4. Technology-specific gotchas (threading, rendering pipeline, etc.)
+
+Register it in `coding-skill-selector` under the appropriate domain.
+
+## Step 4: Create an Interactive Debugger Agent
+
+Create `~/.claude/agents/interactive-<tech>-debugger.md` with pre-loaded skills:
+
+```yaml
+---
+name: interactive-<tech>-debugger
+description: <Tech> debug agent with visual debug bridge — ...
+tools: Read, Glob, Grep, Bash, Skill
+model: sonnet
+skills:
+  - debugging
+  - debug-bridge
+  - debug-bridge-<tech>
+  - <app-specific-interactive-debug-skill if exists>
+---
+```
+
+Body: describe the debug loop for the agent — PID tracking, separate build and run steps, timeout rules.
+
+Then update:
+1. `task-delegation` — add agent to Available Agents table and routing rules
+2. `testing` — reference the new agent for integration verification
+3. `debugging` — reference the new agent in Step 4 (Debug Bridge)

package/templates/skills/domain-gamedev/SKILL.md

@@ -12,19 +12,21 @@ See also: math skill for overflow boundaries (factorial, Fibonacci, float absorp
 | Distance from origin | ULP (precision) | Effect |
 |---------------------|-----------------|--------|
 | 100km | 0.78cm | Fine for most games |
-| 524km (≈2^19m) | 3.1cm → 6.25cm | Unity/Unreal world edge zone |
+| 524km (≈2^19m) | 3.1cm → 6.25cm | Unity world edge zone |
 | 2,097km (2^21m) | 25cm | 5m/s @ 60fps movement ABSORBED — character stops moving |
 | 8,389km (≈2^23m) | 1m | Positions snap to meter grid |
 
 **Absorption formula**: movement absorbed when `velocity * dt < ULP(position) / 2`.
 
+**Unreal gotcha**: Unreal units are CENTIMETERS, not meters — the same ULP boundaries apply per UNIT, so the metric distances above divide by 100 (e.g. 2^21 units ≈ 21km, not 2,097km).
+
 ## Deterministic Physics
 
 **DLL FPU contamination**: Direct3D, printer drivers, sound libraries can silently change FPU control word (precision/rounding mode) without restoring. Assert FPU state after every external call.
 
 **Debug vs release breaks replays**: compiler optimization level alone changes float results even with identical source. All replay participants must use identical binary.
 
-**FMA cross-platform**: PowerPC uses fused multiply-add (one rounding), Intel uses separate mul+add (two roundings) → different results from identical math. Cross-platform determinism requires controlling instruction selection.
+**FMA cross-platform**: fused multiply-add (one rounding) vs separate mul+add (two roundings) → different results from identical math. (The classic PowerPC-has-FMA / Intel-doesn't framing is stale — modern x86 has FMA3 since Haswell and ARM has FMA; today the divergence comes from whether the COMPILER contracts `a*b+c` into FMA, which varies by compiler and flags like `-ffp-contract`.) Cross-platform determinism requires controlling instruction selection.
 
 **x87 vs SSE**: x87 uses 80-bit extended precision internally → double rounding when storing to 64-bit. SSE uses exact 32/64-bit → more predictable. But SSE FTZ/DAZ modes may differ across platforms.
 
@@ -32,7 +34,7 @@ See also: math skill for overflow boundaries (factorial, Fibonacci, float absorp
 
 ## CCD Threshold (verified)
 
-Enable continuous collision detection when: `velocity × dt > object_size`.
+Enable continuous collision detection when: `velocity × dt >= object_size`.
 - 1m object at 60m/s, 60fps: travels 1m/frame → equals object size → CCD needed
 - Below threshold: discrete detection misses contacts (tunneling)
 
@@ -49,7 +51,7 @@ When a state machine waits for an animation-completion event (e.g. xstate `on.AN
 
 ## Parallax Tile Assets: Native Width = Integration Signal
 
-When integrating an artist-authored asset (e.g. `hole_flag.png`) into a row of cyclically-stitched parallax tiles (e.g. `front_1..6.png`), **check native dimensions first**.
+When integrating an artist-authored asset (e.g. `landmark.png`) into a row of cyclically-stitched parallax tiles (e.g. `tile_1..6.png`), **check native dimensions first**.
 
 - If the asset has the **same native width** as the cyclic tiles → it was designed as ONE of the tiles. Insert it into the stitch sequence at a specific anchor position. Don't overlay.
 - If the asset has **different dimensions** → it's a prop sprite meant to sit on top of the tile row (e.g. a character, tree, bush).
@@ -86,7 +88,7 @@ In most 2D engines (Pixi, Phaser, etc.), `sprite.anchor.set(ax, ay)` serves TWO
 
 **Use case**: to rotate a sprite around a specific feature of its PNG (e.g. the left rim of a hazard/foot of a character), put the anchor at that feature's normalized texture coords. Then set `sprite.position` to the world location of that feature and `sprite.rotation` — the feature stays locked in place while the rest swings.
 
-**Gotcha**: anchor and pivot are NOT separate in Pixi's Sprite. If you need them decoupled, wrap the Sprite in a Container and rotate the Container.
+**Gotcha**: in Pixi the Sprite's `anchor` drives BOTH roles — placement point and rotation origin are not independently settable through it (a separate `pivot` property exists on every Container, but changing it shifts where `position` lands too). If you need placement and rotation origin decoupled, wrap the Sprite in a Container and rotate the Container.
 
 ## Heightmap From PNG Alpha — Pre-sample Once
 
@@ -127,7 +129,7 @@ When the follow formula is `cameraY = targetScreenY − worldY × zoom` (standar
 - Ball RISES in world → `worldY` DECREASES → `cameraY` INCREASES.
 - `Math.min(flightTarget, idleCameraY)` reads as "never go ABOVE idle" in human terms, but `cameraY` for a higher ball is NUMERICALLY LARGER than the idle value — so `Math.min` pins the camera to idle and BLOCKS the follow-up. The correct direction is `Math.max` (if clamping against an upper bound on camera Y) or no clamp at all.
 
-**Verify before shipping**: plug in two concrete numbers — ball at rest and ball at peak — and compute `cameraY` for each. The one with higher `worldY` (lower on screen) should yield a MORE NEGATIVE `cameraY` if the pivot is above the horizon pivot, or more positive if below. If the clamp picks the wrong side, the camera becomes useless at exactly the moment it needs to work.
+**Verify before shipping**: plug in two concrete numbers — ball at rest and ball at peak — and compute `cameraY` for each. With `cameraY = targetScreenY − worldY × zoom`, the endpoint with the LARGER `worldY` (ball lower in the world) yields the SMALLER `cameraY`. If the clamp picks the wrong side, the camera becomes useless at exactly the moment it needs to work.
 
 **Rule**: every time you combine `screenAnchor − worldPos × zoom` with a `Math.min`/`Math.max`, write the two endpoints on paper. Don't trust the human-language reading of the clamp.
 
@@ -160,3 +162,51 @@ Sub-pixel for flat terrain, but visible (1+ px sliver) on noticeably tilted band
 | > 40ms | Unacceptable for rhythm/FPS |
 
 Humans react to audio faster than visual → audio lag more noticeable than dropped frames.
+
+## Crash / Multiplier-Game RTP (Aviator / Bustabit style)
+
+**Canonical crash math**: `crashPoint = (1−he)/(1−U)`, `U∈[0,1)`. This gives `P(crashPoint ≥ x) = (1−he)/x` for `x≥1`. EV at any cashout target `x` = `P(survive to x)·x = (1−he)/x · x = 1−he`. RTP = `1−houseEdge`, **strategy-independent** — the only clean way to get that property.
+
+**GOTCHA — forced/consolation payouts break RTP and strategy-independence.**
+Any guaranteed payout on a step the round did NOT crash on (a "soft-loss step saves your accumulated winnings" mechanic, forced cashout on miss, consolation bonus) is EV-positive: it pays value the crash-CDF budget never debited. Effect:
+- Global RTP > target.
+- "Ride longer" becomes the dominant strategy → strategy-independence destroyed.
+
+Only voluntary cashouts and a correctly-priced cap/jackpot are EV-neutral. "Soft-loss that saves X" is fundamentally incompatible with strategy-independent crash RTP without full game-math re-optimization around the save mechanics.
+
+**GOTCHA — flat auto-paid cap inflates AFK strategy EV.**
+A jackpot cap paid regardless of player action gives the never-cash (AFK) strategy `EV = P(cap)·cap`. EV-neutral only if `P(cap) = (1−he)/cap` exactly (the same CDF). Combine with ANY other forced payout and AFK RTP overshoots the target by tens of percent.
+
+**GOTCHA — finite step chain caps reachable multiplier.**
+An N-step chain with per-step multiplier `∈[lo,hi]` tops out at `≈hi^(N−1)`. Crash points above that are structurally unreachable → RTP sags BELOW target for high cashout targets and for never-cash. "Exactly `1−he`, globally strategy-independent" is FALSE for a finite chain; it only holds approximately for reachable targets.
+
+| N steps | per-step max | reachable ceiling |
+|---------|-------------|------------------|
+| 5 | ×3 | ×81 |
+| 7 | ×2.5 | ×244 |
+| 10 | ×2 | ×512 |
+
+**GOTCHA — PRNG stream independence for crashPoint.**
+`crashPoint` must be statistically independent of the per-step multiplier draws. Drawing it as the first output then the curve from subsequent draws of the same stream is fine (good PRNG outputs are uncorrelated). A separate stream keyed by a near-identical seed through a weak hash (e.g. `seed` vs `seed+":crash"` via FNV-1a → mulberry32) can silently correlate and inflate or deflate RTP. Verify empirically with a large Monte Carlo sweep — don't assume independence from the construction.
+
+**GOTCHA — conditional sub-population EV slices carry structural bias.**
+Filtering a Monte Carlo run to "rounds containing event X" and asserting the per-target RTP corridor of the slice ≈ global RTP is wrong whenever X correlates with round length or terminal outcome. Two independent causes:
+(a) *Chain-truncating event*: bonus steps that mostly emit at the crash-branch terminal — the round ends there — so high targets are structurally unreachable. Per-target RTPs of the slice decline monotonically with target; no tolerance widening fixes it.
+(b) *Compensation/dampening gate*: forced-miss rounds replace the event step with a miss variant and never enter the filtered slice — rounds that do enter carry inherited selection bias → the slice mean lands well below the global RTP.
+Pin only the upper bound (no target > 1.10–1.15) to catch +EV regressions, plus a wide mean band (±0.10). Drop per-target corridor, spread, and ride-RTP assertions on any slice with structural correlation between the filter condition and the round's terminal outcome.
+
+**PROCESS GOTCHA — Monte Carlo BEFORE porting or regenerating fixtures.**
+Validate the EV model with a sweep across multiple fixed cashout targets before porting to a second language or regenerating golden fixtures. An analytically "correct" model can hide EV-design bugs (forced payouts, chain ceiling, PRNG correlation) that only a per-target simulation exposes. Porting first = double rework when the math turns out wrong.
+
+**GOTCHA — economic model must not silently override a player-visible physics event.**
+When a deterministic outcome layer (pre-drawn crash point / book-based result) is draped over a physics renderer, scope any economic reclassification to outcomes the player CANNOT SEE. A physical impact the player watches happen (the ball rams an obstacle and bounces) MUST terminate consistently with what was shown — overriding it back to "safe, continue" so the book stays tidy produces a contradiction caught in the first playtest (observed: the ball visibly hit an obstacle yet the multiplier kept climbing). Rule: renderer-derived classification wins for any event the player can see; the economic model may only override outcomes that are visually indistinguishable.
+
+## Virtual-Scroll / Treadmill Takeover — Match Speed at the Handoff Seam
+
+When forward motion transitions from **real translation** (object moves in world-X, camera follows) to a **virtual scroll / treadmill** (object parked at a fixed screen X, background streamed past it to fake motion), the streamed background speed must MATCH the object's prior real forward speed at the seam, then ease down. A speed discontinuity — especially a collapse — reads as the object STOPPING, not as continued motion.
+
+**Concrete case**: a flying ball soared at ~1700 px/s (real X travel, camera following), then a "cruise" phase parked the ball and streamed the sky at a constant 280 px/s — a ~6× speed collapse at the seam. Players read it as "the ball stopped." Fix: start the treadmill at the soar's exit speed (`≈ (end.x − start.x) / duration`, clamped to a sane max), then smoothstep-decelerate to the idle drift speed (280 px/s). The background keeps moving at the prior rate and gently settles — reads as continuous forward flight arriving into a hover.
+
+**Measurement gotcha**: if the engine time-scales animation (e.g. `gsap.globalTimeline.timeScale(speed)` for a `?speed` param), the sampled background px/s is `game-speed × timeScale`. Multiply back by `1/timeScale` before comparing to your intended game-time speed, or a correct value reads as "too slow."
+
+**Secondary motion gotcha**: a vertical overlay (e.g. wind weave) at large amplitude (±70 px) on a now-slow background DOMINATES perception — reads as "bobbing in place." Keep secondary motion small relative to apparent forward speed (±70 → ±26 px fixed it).