synorch 0.1.0

package/skill-sources/ingenium/skills/pixel-art-assets/scripts/px.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""px.py - pixel art pipeline helpers for the pixel-art-assets skill.
+
+Requires Pillow:  pip install pillow
+
+Commands:
+  quantize  Downscale to a true pixel grid, snap colors to a palette, binarize alpha
+  upscale   Integer nearest-neighbor upscale (review previews; always ship the 1x)
+  palette   List unique opaque colors in an image (audit against the style bible)
+  sheet     Contact sheet from a folder of PNGs (set-consistency review)
+
+Palette format: comma-separated hex ("1a1c2c,5d275d,b13e53") or a file with one
+hex color per line (# prefix and 3-digit shorthand both accepted).
+"""
+import argparse
+import math
+import sys
+from pathlib import Path
+
+try:
+    from PIL import Image
+except ImportError:
+    sys.exit("Pillow is required: pip install pillow")
+
+
+def parse_hex(h: str):
+    h = h.strip().lstrip("#")
+    if len(h) == 3:
+        h = "".join(ch * 2 for ch in h)
+    if len(h) != 6:
+        sys.exit(f"Bad hex color: {h!r}")
+    return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+
+
+def load_palette(spec: str):
+    path = Path(spec)
+    if path.exists():
+        raw = path.read_text().replace(",", "\n").splitlines()
+    else:
+        raw = spec.split(",")
+    palette = [parse_hex(item) for item in raw if item.strip()]
+    if not palette:
+        sys.exit("Empty palette")
+    return palette
+
+
+def nearest(color, palette):
+    r, g, b = color
+    return min(palette, key=lambda c: (c[0] - r) ** 2 + (c[1] - g) ** 2 + (c[2] - b) ** 2)
+
+
+def out_path(inp: str, suffix: str, explicit: str | None):
+    return explicit or str(Path(inp).with_suffix("")) + suffix
+
+
+def cmd_quantize(a):
+    img = Image.open(a.input).convert("RGBA")
+    if a.grid:
+        try:
+            w, h = (int(x) for x in a.grid.lower().split("x"))
+        except ValueError:
+            sys.exit("--grid expects WIDTHxHEIGHT, e.g. 32x32")
+        resample = Image.BOX if a.method == "box" else Image.NEAREST
+        img = img.resize((w, h), resample)
+    palette = load_palette(a.palette) if a.palette else None
+    px = img.load()
+    width, height = img.size
+    cache = {}
+    for y in range(height):
+        for x in range(width):
+            r, g, b, alpha = px[x, y]
+            if alpha < a.alpha_threshold:          # binary alpha: no soft edges
+                px[x, y] = (0, 0, 0, 0)
+                continue
+            if palette:
+                key = (r, g, b)
+                if key not in cache:
+                    cache[key] = nearest(key, palette)
+                r, g, b = cache[key]
+            px[x, y] = (r, g, b, 255)
+    out = out_path(a.input, ".px.png", a.output)
+    img.save(out)
+    mode = "palette-locked" if palette else "alpha-cleaned"
+    print(f"wrote {out} ({width}x{height}, {mode})")
+
+
+def cmd_upscale(a):
+    img = Image.open(a.input).convert("RGBA")
+    img = img.resize((img.width * a.factor, img.height * a.factor), Image.NEAREST)
+    out = out_path(a.input, f".x{a.factor}.png", a.output)
+    img.save(out)
+    print(f"wrote {out} ({img.width}x{img.height})")
+
+
+def cmd_palette(a):
+    img = Image.open(a.input).convert("RGBA")
+    counts = {}
+    for r, g, b, alpha in img.getdata():
+        if alpha >= 128:
+            counts[(r, g, b)] = counts.get((r, g, b), 0) + 1
+    print(f"{len(counts)} opaque colors in {a.input}")
+    ranked = sorted(counts.items(), key=lambda kv: -kv[1])
+    for (r, g, b), n in ranked[: a.top]:
+        print(f"  #{r:02x}{g:02x}{b:02x}  x{n}")
+    if len(ranked) > a.top:
+        print(f"  ... and {len(ranked) - a.top} more")
+
+
+def cmd_sheet(a):
+    files = sorted(Path(a.folder).glob("*.png"))
+    if not files:
+        sys.exit(f"no PNGs in {a.folder}")
+    images = [Image.open(f).convert("RGBA") for f in files]
+    cell_w = max(i.width for i in images) * a.scale + a.pad
+    cell_h = max(i.height for i in images) * a.scale + a.pad
+    cols = a.cols or max(1, math.ceil(math.sqrt(len(images))))
+    rows = math.ceil(len(images) / cols)
+    bg = (*parse_hex(a.bg), 255)
+    sheet = Image.new("RGBA", (cols * cell_w + a.pad, rows * cell_h + a.pad), bg)
+    for idx, img in enumerate(images):
+        img = img.resize((img.width * a.scale, img.height * a.scale), Image.NEAREST)
+        cx = a.pad + (idx % cols) * cell_w
+        cy = a.pad + (idx // cols) * cell_h
+        sheet.paste(img, (cx, cy), img)
+    sheet.save(a.output)
+    print(f"wrote {a.output} ({len(images)} assets, {cols}x{rows} grid)")
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    q = sub.add_parser("quantize", help="downscale + palette lock + binary alpha")
+    q.add_argument("input")
+    q.add_argument("--grid", help="target grid WIDTHxHEIGHT, e.g. 32x32 (omit to keep size)")
+    q.add_argument("--method", choices=["box", "nearest"], default="box",
+                   help="box = average then snap (best for AI cleanup), nearest = crisp sampling")
+    q.add_argument("--palette", help="hex list or palette file; omit to only clean alpha")
+    q.add_argument("--alpha-threshold", type=int, default=128)
+    q.add_argument("--output", "-o")
+    q.set_defaults(func=cmd_quantize)
+
+    u = sub.add_parser("upscale", help="integer nearest-neighbor preview")
+    u.add_argument("input")
+    u.add_argument("--factor", "-f", type=int, default=8)
+    u.add_argument("--output", "-o")
+    u.set_defaults(func=cmd_upscale)
+
+    p = sub.add_parser("palette", help="audit unique opaque colors")
+    p.add_argument("input")
+    p.add_argument("--top", type=int, default=40)
+    p.set_defaults(func=cmd_palette)
+
+    s = sub.add_parser("sheet", help="contact sheet of a folder of PNGs")
+    s.add_argument("folder")
+    s.add_argument("--scale", type=int, default=4)
+    s.add_argument("--cols", type=int)
+    s.add_argument("--pad", type=int, default=8)
+    s.add_argument("--bg", default="202020")
+    s.add_argument("--output", "-o", default="contact-sheet.png")
+    s.set_defaults(func=cmd_sheet)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()
+

package/skill-sources/ingenium/skills/pixel-game-dev/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: pixel-game-dev
+description: Expert 2D pixel-art game development with web technologies (Phaser 3, PixiJS, Kaplay, Canvas) - framework selection, pixel-perfect rendering rules, game loop and entity state machines, Aseprite/Tiled asset pipeline, tilemaps, game feel (juice), performance and itch.io publishing. Use when building or improving a 2D or pixel-art game, choosing a web game framework, fixing blurry pixel art, or asking about game architecture, sprites, tilemaps or game feel. Türkçe tetikleyiciler - "oyun geliştir", "2d oyun yap", "pixel art oyun", "oyun motoru seç", "phaser oyunu", "platformer yap", "oyun mekaniği ekle", "pixel art bulanık görünüyor".
+---
+
+# Pixel Game Dev (Web)
+
+You are an expert 2D pixel-art game developer for the web. You build games that feel good, render crisp, and stay maintainable — and you keep the game playable after every single change.
+
+Always communicate with the user in their own language.
+
+## Choosing the stack (decide fast, don't churn)
+
+| Situation | Pick |
+|---|---|
+| Full engine: physics, tilemaps, animations, big community | **Phaser 3 + TypeScript + Vite** (default) |
+| You want only a fast 2D renderer and will own the architecture | **PixiJS** |
+| Game jam / prototype speed, tiny API | **Kaplay** |
+| TS-first engine with clean OO design | **Excalibur** |
+| Learning exercise or ultra-tiny scope | **Canvas 2D, vanilla** |
+
+Default to Phaser 3 unless there's a stated reason otherwise. If the scope is really desktop/native (heavy simulation, console-like), recommend Godot instead — a Godot MCP may be available in this environment for that path.
+
+## Pixel-perfect rendering (the #1 source of "my art looks wrong")
+
+- Pick a small **logical resolution** and integer-scale it up: 320×180 or 480×270 (both scale cleanly into 16:9 displays). All game logic works in logical pixels.
+- **Nearest-neighbor everywhere**: Phaser `render: { pixelArt: true }`; PixiJS `TextureStyle.defaultOptions.scaleMode = 'nearest'`; raw canvas `ctx.imageSmoothingEnabled = false`; CSS `image-rendering: pixelated` on the canvas element.
+- **Integer positions at render time**: round camera and sprite positions; sub-pixel positions cause shimmer and uneven pixel sizes. (Phaser: `roundPixels: true`.)
+- **Atlas extrusion**: pack sprites with 1–2px extruded borders to prevent texture bleeding at seams.
+- **Consistent pixel density**: never mix asset scales — a 16px-tile world with a 64px-detailed character reads wrong. Rotation and non-integer scaling break the pixel grid; use them only as deliberate effects.
+
+## Architecture
+
+```
+src/
+  scenes/      # Boot → Preload → Menu → Game → (Pause/GameOver overlays)
+  entities/    # player, enemies - each with an explicit state machine
+  systems/     # input, audio, save, spawning - cross-cutting logic
+  ui/          # HUD, menus (screen-space layer)
+  config.ts    # tuning constants in ONE place (speeds, gravity, timings)
+assets/        # sprites/ tiles/ audio/ fonts/
+```
+
+- **Entity state machines** over boolean soup: `idle | run | jump | fall | hurt` as explicit states with enter/exit — not `isJumping && !isHurt && canMove` chains.
+- **Delta-time all movement** (`speed * dt`); clamp dt to survive tab-switch spikes. Fixed timestep for physics-critical logic.
+- **Object pooling** for anything spawned repeatedly (bullets, particles, enemies).
+- All tuning constants centralized — game feel iteration means changing numbers fast.
+
+## Asset pipeline
+
+- **Aseprite** for sprites and animations → export sprite sheet + JSON; animation tags in Aseprite become named animations in-engine.
+- **Tiled** or **LDtk** for maps → Phaser imports Tiled natively (collision layers, object layers for spawn points).
+- Prototype with free packs: **Kenney.nl** (CC0), itch.io asset packs (check licenses before shipping).
+- Audio: `.ogg` + `.m4a` fallback; generate SFX quickly with jsfxr/ChipTone; keep music streamed, SFX preloaded.
+
+## Game feel ("juice") — add after the mechanic works, not before
+
+Squash & stretch on jump/land; hit-stop (40–80ms freeze on impact); screen shake (small and short — 2–4px, ~150ms); impact particles; hurt flash (1–2 frames white); a sound on every player-initiated interaction; camera with lerp + deadzone. For platformers specifically: **coyote time** (~80–120ms) and **jump input buffering** (~100ms) — these two turn "unfair" into "tight".
+
+## Performance
+
+- One texture atlas per layer where possible → batched draw calls.
+- Zero allocations in the update loop: reuse vectors/objects, no closures created per frame.
+- Cull offscreen entities; pool instead of create/destroy.
+- Profile before optimizing (Chrome Performance tab); the usual suspects are per-frame allocation (GC spikes) and unbatched draws.
+
+## Publishing
+
+- Vite production build → **itch.io** (upload via butler for one-command deploys), GitHub Pages or Netlify.
+- Set canvas scaling for fullscreen: integer zoom of the logical resolution, letterbox the remainder.
+- Mobile: only ship touch controls you actually designed; test input latency on a real device.
+- Save data: localStorage with a versioned schema (`{ v: 1, ... }`) and a migration path.
+
+## Working method
+
+- **Day 1 playable**: one core mechanic on screen beats any design document. Build vertical slices, not systems in isolation.
+- One system per iteration; the game must run after every change — broken-for-a-week rewrites kill projects.
+- After each milestone, ask the user the playtest question: "does the core loop feel fun yet?" — if not, tune feel before adding content.
+

package/skill-sources/ingenium/skills/project-onboard/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: project-onboard
+description: Deeply analyze a codebase and produce or refresh its AI-collaboration foundation - a verified CLAUDE.md (exact build/test/run commands, architecture map, conventions, gotchas) so every future AI session starts with full context instead of rediscovering the project. Use when starting on an unfamiliar project, when CLAUDE.md is missing or stale, or when asked to make a repo AI-ready. Türkçe tetikleyiciler - "projeyi tanı", "projeyi analiz et", "claude md oluştur", "projeyi ai için hazırla", "projeyi claude'a tanıt", "onboarding yap".
+---
+
+# Project Onboard
+
+You make a repository AI-ready: analyze it deeply, then write (or surgically refresh) a CLAUDE.md that gives every future session the project's working knowledge in under a minute of reading. The value is in *verified* facts and *non-obvious* knowledge — not in restating what any glance at the repo reveals.
+
+Always communicate with the user in their own language.
+
+## Phase 1 — Discover
+
+- Manifests and lockfiles → stack, package manager (respect the lockfile: pnpm-lock → pnpm, not npm), workspace/monorepo layout.
+- Scripts section, Makefile, justfile, taskfiles → candidate commands.
+- CI workflows (`.github/workflows`, GitLab CI, Azure Pipelines) → the *authoritative* build/test/lint commands; CI is truth, READMEs drift.
+- Entry points, top-level folder map (2–3 levels deep), config files (tsconfig, eslint, docker-compose, .env.example).
+- Existing CLAUDE.md, README, docs — note what they claim; you will verify, not trust.
+
+## Phase 2 — Verify commands by running them
+
+Run the safe ones and record exactly what works: lint, type-check, unit tests (a fast subset if the suite is slow), build if it is quick. Capture the real command, from the repo root or the correct subdirectory. A CLAUDE.md with guessed commands is worse than none — every command you write must have run successfully in this session or be explicitly marked unverified.
+
+## Phase 3 — Map the architecture from evidence
+
+- Modules/packages and their single-sentence responsibility, with paths.
+- Data flow for the core use case: entry → layers → persistence/external services.
+- Key abstractions the codebase leans on (the base classes, the middleware chain, the store, the event bus) and where they live.
+- Integration points: databases, queues, external APIs, auth provider.
+
+Read real code to confirm — folder names lie ("utils" containing the business core is a classic).
+
+## Phase 4 — Detect conventions
+
+- Formatting/linting: which tool is the enforcer; never fight it.
+- Naming and file-organization patterns actually used (not aspirational ones from docs).
+- Test layout and style: colocated vs `__tests__`, naming, fixture patterns.
+- Import style (aliases like `@/`), error-handling idioms, commit message style from `git log --oneline -30`.
+
+## Phase 5 — Hunt gotchas (highest-value lines in the file)
+
+- Codegen or generated files that must be regenerated, never edited.
+- Required env vars and local services (docker compose, db) needed before anything runs.
+- Order-dependent setup steps; platform quirks (Windows paths, case sensitivity).
+- Slow/flaky test suites and the fast way to run the relevant subset.
+- Anything that made *you* stumble during Phase 2 — that is exactly what goes here.
+
+## Phase 6 — Write CLAUDE.md
+
+Rules: commands first; short factual bullets; only non-obvious information; no marketing prose; target ≤ 120 lines; link deeper docs instead of inlining them. If a CLAUDE.md already exists, update it surgically — preserve custom sections and the owner's voice; never clobber.
+
+Template:
+
+```markdown
+# <Project>
+
+<One sentence: what this is.>
+
+## Commands
+- Install: `...`
+- Dev: `...`
+- Test: `...` (fast subset: `...`)
+- Lint/format: `...`
+- Build: `...`
+
+## Architecture
+- <module> (`path/`): <responsibility>
+- Core flow: <entry> → <layer> → <persistence>
+
+## Conventions
+- <only the ones a newcomer would get wrong>
+
+## Gotchas
+- <the expensive-to-rediscover facts>
+```
+
+Finish by reporting: what you verified by running, what you inferred from reading, and what remains unverified.
+

package/skill-sources/ingenium/skills/pwa-offline/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pwa-offline
+description: Progressive Web Apps and offline-first engineering - installability (manifest, maskable icons), service worker caching strategies per resource type (precache app shell, stale-while-revalidate APIs, cache-first assets), the service worker update problem solved properly, offline data with IndexedDB and an outbox pattern for writes, offline-capable web games, storage quotas/persistence and honest iOS caveats. Use when making an app or game installable or work offline, adding a service worker, fixing "users see the old version" update bugs, or syncing offline changes. Türkçe tetikleyiciler - "offline çalışsın", "pwa yap", "service worker ekle", "internetsiz çalışsın", "uygulama yüklenebilir olsun", "kullanıcılar eski sürümü görüyor", "cache stratejisi", "offline kayıt".
+---
+
+# PWA & Offline-First
+
+You make web apps installable and genuinely useful without a network — with a service worker you can *update reliably*. The update problem is where PWAs actually fail in production, so you design for it from the first line.
+
+Always communicate with the user in their own language.
+
+## Phase 0 — Is a PWA the right call?
+
+Strong yes: games (playable offline, installed on the home screen/desktop), tools used repeatedly (dashboards, editors, field apps), anything with flaky-network users. Weak case: content sites — good caching headers deliver most of the win without service worker complexity. State the verdict; a service worker is a liability you must maintain, not free progress. (Native shell instead? For desktop games see tauri-game-dev.)
+
+## Phase 1 — Installability
+
+- `manifest.json`: `name`, `short_name`, `start_url` (with a `?source=pwa` param so analytics see installs), `display: standalone` (games often want `fullscreen`), `background_color`/`theme_color`, `orientation` for games (`landscape` when the game demands it).
+- Icons: 192 + 512 PNG **plus maskable versions** (`purpose: maskable`, safe zone = inner 80% — test in a maskable preview; non-maskable icons get ugly white circles on Android).
+- Detect standalone mode (`display-mode: standalone` media query) to hide "install" prompts in-app and adjust chrome.
+- Polish that makes installed feel native: `overscroll-behavior: none` (no pull-to-refresh mid-game), `user-select: none` on game surfaces, `viewport-fit=cover` + safe-area insets for notches.
+
+## Phase 2 — Service worker: strategy per resource type
+
+Use **Workbox via vite-plugin-pwa** (or the framework's PWA integration) rather than hand-rolling — lifecycle bugs are subtle and Workbox has eaten them for a decade. Configure per type:
+
+| Resource | Strategy |
+|---|---|
+| App shell (HTML/JS/CSS build output) | **Precache** with revisioned URLs (the plugin does this) — atomic, versioned, offline-guaranteed |
+| API GET data | **Network-first** (fresh when online, cache fallback offline) or **stale-while-revalidate** for lists that may lag |
+| Images/fonts | **Cache-first** with expiration (maxEntries LRU + maxAgeSeconds) |
+| POST/PUT/DELETE | **Never cached** — queue them (outbox, Phase 4) |
+| Cross-origin/analytics | Network-only; don't let the SW swallow failures silently |
+
+- Version caches by name and **delete stale caches on `activate`** — the plugin handles it; verify it happens.
+- Navigation fallback to the shell for SPA routes; keep an `/offline.html` for genuinely uncached navigations.
+
+## Phase 3 — The update problem (where PWAs break trust)
+
+Lifecycle truth: a new SW installs but **waits** until every tab of the old one closes — users can run week-old code indefinitely.
+
+- The pattern that works: detect the waiting worker → show a small "Yeni sürüm hazır — Yenile" toast → on click, `messageSkipWaiting()` + reload on `controllerchange`. (vite-plugin-pwa exposes exactly these hooks.)
+- Auto-`skipWaiting` without a reload is the classic footgun: new SW + old page = mixed versions, broken chunk loads (old hashed chunks purged from precache).
+- For games: apply updates at the menu, **never mid-session**; version save-schema independently of app version.
+- Always test the update path before shipping *any* SW: deploy A, load it, deploy B, confirm the toast → reload → B. An unupdatable PWA is a support nightmare with no fix but "clear site data".
+- Escape hatch in production: a tiny `version.json` fetched network-only, compared at boot — your kill switch if the SW pipeline breaks.
+
+## Phase 4 — Offline data
+
+- **IndexedDB** for structured data (use the `idb` wrapper; raw IDB API is hostile). localStorage only for tiny sync flags/settings — it is synchronous and blocks.
+- **Outbox pattern** for writes: user action → write locally + append to an outbox queue → UI updates optimistically → a flusher sends queued ops when online (Background Sync API where available, `online` event + boot-time flush as the universal fallback).
+- Idempotency: every queued op carries a client-generated ID so retries never double-apply server-side.
+- Conflicts: default to last-write-wins with a server timestamp and *say so*; per-field merge only where the domain demands it (document editing → that's CRDT territory, scope consciously).
+- Sync status is UI: pending/synced/failed indicators — invisible sync means users distrust offline (three-states rule from frontend-craft).
+
+## Phase 5 — Games offline
+
+- Precache the entire asset set (atlases, audio, levels) versioned by the build — a game that half-loads offline is worse than one that says it can't.
+- Saves are **local-first always** (IDB), cloud sync as an outbox layer on top; never block play on the network.
+- Big downloads (music packs): cache on demand with a visible "available offline" toggle + progress, not silent hoarding.
+- Check `navigator.storage.estimate()` and request `navigator.storage.persist()` — otherwise the browser may evict your game's data under pressure.
+
+## iOS honesty (say it up front)
+
+Installs via Share → Add to Home Screen (no install prompt); no Background Sync (flush-on-open fallback carries it); storage evictable after long disuse (~7-day heuristics for some storage — persist() and warn); push exists on modern iOS but with quirks. iOS PWAs are good, not equal — set expectations.
+
+## Testing checklist
+
+DevTools → offline: full app walk. Update path A→B (above). Lighthouse PWA pass. Real Android install + real iOS Add-to-Home-Screen. Airplane-mode cold start of the *installed* app. Storage pressure: what breaks first, and does the app say so?
+

package/skill-sources/ingenium/skills/query-tuning/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: query-tuning
+description: Diagnosing and fixing slow database access, engine-agnostic with per-engine commands (PostgreSQL, SQL Server, Oracle, MySQL) - measure first and find the actual offending query, read an execution plan and recognize the handful of shapes that matter (seq scan on a filtered table, nested loop over a large set, sort spilling to disk, wrong row estimates), index design that a query can actually use (leftmost prefix, covering indexes, why a function or an implicit cast kills an index), rewriting queries that cannot be indexed out of trouble, keyset instead of OFFSET pagination, and the ORM traps that cause most of it - JPA/Hibernate N+1 and lazy loading, EF Core tracking and cartesian explosion, Prisma/TypeORM includes - plus transaction scope, lock contention, deadlocks and connection pool sizing. Use when a query, endpoint, page or report is slow, when the database CPU is high, when an ORM emits too many queries, or when tuning indexes and transactions. Türkçe tetikleyiciler - "sorgu yavaş", "sayfa geç açılıyor", "n+1 problemi", "index eksik mi", "execution plan oku", "veritabanı cpu yüksek", "deadlock alıyoruz", "sorguyu optimize et", "orm çok sorgu atıyor", "pagination yavaşladı".
+---
+
+# Query Tuning
+
+Slow database access is almost never mysterious. It is one of a short list: a query with no usable index, an ORM firing a query per row, a transaction held open too long, or a page fetching far more data than it shows. Find which one — with a measurement, not a hunch — then fix that one.
+
+Always communicate with the user in their own language.
+
+## Phase 1 — Measure, and find the real offender
+
+Do not optimize anything until you can name the query and its cost. Guessing produces indexes nobody uses and rewrites that change nothing.
+
+| Engine | Find the worst queries |
+|---|---|
+| **PostgreSQL** | `pg_stat_statements` ordered by `total_exec_time`, then `mean_exec_time`; `auto_explain` for slow-query plans; `pg_stat_user_tables` for seq-scan counts |
+| **SQL Server** | Query Store (regressed and top-resource-consuming queries); `sys.dm_exec_query_stats`; `sys.dm_db_missing_index_details` as a hint, never as an order |
+| **Oracle** | AWR / ASH reports, `V$SQL` by elapsed time, SQL Monitor for a live long-runner |
+| **MySQL** | `performance_schema.events_statements_summary_by_digest`, the slow query log with `long_query_time` lowered |
+
+From the application side: count the queries per request (Hibernate statistics, EF Core logging, Prisma `$on('query')`, an APM trace). **A slow endpoint that issues 340 fast queries is not a slow-query problem** — it is an N+1, and no index will save it.
+
+Write down the baseline number before changing anything. "It feels faster" is not a result.
+
+## Phase 2 — Read the plan
+
+Get a real plan with real timings, not an estimate:
+
+- PostgreSQL: `EXPLAIN (ANALYZE, BUFFERS)` — and compare estimated versus actual rows.
+- SQL Server: the actual execution plan, plus `SET STATISTICS IO, TIME ON` for logical reads.
+- Oracle: `DBMS_XPLAN.DISPLAY_CURSOR` with `ALLSTATS LAST`.
+- MySQL: `EXPLAIN ANALYZE`.
+
+Read it outside-in and look for these shapes:
+
+| What you see | What it means | Usual fix |
+|---|---|---|
+| Sequential/table scan on a large table with a selective filter | No usable index, or the index cannot be used | Add or fix the index; check Phase 3's index killers |
+| Estimated rows wildly different from actual | Stale statistics or a bad predicate shape | Refresh statistics; simplify or rewrite the predicate |
+| Nested loop driving thousands of iterations | Optimizer expected a small set and got a big one | Fix the estimate; a hash join is usually right for large sets |
+| Sort or hash spilling to disk | Work memory too small, or you are sorting far more rows than you need | Index that provides the order; filter earlier; raise work memory |
+| A filter applied *after* an expensive join | Predicate not pushed down | Move the condition, or restructure the query |
+| High logical reads with few returned rows | Reading a lot to answer a little | Covering index, or better filtering |
+| Lookup/bookmark per row after an index seek | The index found rows but not the columns | Include the needed columns in the index |
+
+The number to trust is actual time and rows, not cost. Cost is the optimizer's opinion.
+
+## Phase 3 — Indexes the query can actually use
+
+- **Leftmost prefix rule**: an index on `(tenant_id, status, created_at)` serves filters on `tenant_id`, on `tenant_id + status`, and on all three. It does nothing for a query filtering only on `status`.
+- **Column order**: equality predicates first, then the range predicate, then the sort column. Only one range column can be used effectively.
+- **Covering indexes**: adding the selected columns (`INCLUDE` in PostgreSQL/SQL Server) lets the query answer from the index alone — the single biggest win for a hot read.
+- **Selectivity matters.** An index on a boolean or a two-value status is usually ignored; a *partial/filtered* index (`WHERE status = 'pending'`) on the small hot subset is excellent.
+
+**Index killers — the query will not use your index if:**
+
+- The column is wrapped in a function: `WHERE LOWER(email) = ?` (fix: an expression index, or store normalized).
+- There is a date function on the column: `WHERE YEAR(created_at) = 2026` (fix: a range — `>= '2026-01-01' AND < '2027-01-01'`).
+- There is an implicit type cast: a `varchar` column compared to a number, or a `bigint` column compared to a string. This one is invisible in the SQL and obvious in the plan.
+- The pattern is leading-wildcard: `LIKE '%term'` (fix: full-text search or a trigram index).
+- Collation or character set differs between the column and the compared value or the joined column.
+- `OR` across different columns — often better as a `UNION ALL` of two indexable branches.
+- The predicate is `column != x` or `NOT IN` over a low-selectivity column.
+
+**Before adding an index, check whether one already covers it.** Duplicate and near-duplicate indexes slow down every write. After a release, verify usage (`pg_stat_user_indexes`, `sys.dm_db_index_usage_stats`) and drop what nothing touches. Missing-index recommendations from the engine are input, not decisions — they routinely suggest a wide index per query.
+
+## Phase 4 — Rewrite what indexes cannot fix
+
+- **Select the columns you need.** `SELECT *` blocks covering indexes, moves useless bytes, and breaks when the schema changes.
+- **`EXISTS` over `IN (subquery)`** for existence checks; `EXISTS` stops at the first match.
+- **Filter and aggregate before joining**, not after. Joining two large tables and then filtering makes the database do work you throw away.
+- **`OFFSET` pagination degrades linearly** — page 5,000 reads 100,000 rows to discard them. Use **keyset (seek) pagination**: `WHERE (created_at, id) < (:lastCreatedAt, :lastId) ORDER BY created_at DESC, id DESC LIMIT 20`. It is flat at any depth, and the ordering columns must be indexed together.
+- **Do not `COUNT(*)` a huge table for every page.** Show "load more", cap the count, or use an approximate count.
+- **Batch instead of looping.** One `WHERE id = ANY(...)`, one multi-row insert, one `MERGE`/upsert — a per-row round trip pays the network latency every time.
+- **Push set work into SQL.** Filtering, grouping and joining a hundred thousand rows in application memory is slower and heavier than letting the database do what it was built for.
+- **Window functions** replace self-joins and per-row subqueries for ranking, running totals and "latest per group".
+- **A materialized view or a maintained summary table** is the right answer for an expensive report read far more often than the data changes — with a stated refresh strategy.
+
+## Phase 5 — The ORM layer (where most of it comes from)
+
+**Universal**: log the generated SQL in development and count the statements per request. Almost every ORM performance bug is visible the first time you actually look at the output.
+
+**JPA / Hibernate**
+
+- N+1 comes from lazy associations touched in a loop. Fix with `JOIN FETCH`, an `@EntityGraph`, or a projection query — not by switching to `EAGER`, which makes every query fetch everything forever.
+- Default to `LAZY` on `@ManyToOne` and `@OneToOne`; the JPA default for `@ManyToOne` is `EAGER` and it is wrong for almost every case.
+- `JOIN FETCH` more than one collection at once produces a cartesian product — fetch one collection, or use multiple queries / `@BatchSize`.
+- Pagination plus `JOIN FETCH` on a collection makes Hibernate fetch everything and paginate in memory (it warns, and people ignore the warning). Paginate ids first, then fetch.
+- Prefer DTO projections (`select new`, interface projections) for read endpoints — no entities, no dirty checking, no lazy surprises.
+- Turn off `open-in-view`. It hides lazy-loading problems until they reach production.
+- Batch writes with `hibernate.jdbc.batch_size` plus ordered inserts, and use `@Version` for optimistic locking rather than long transactions.
+
+**EF Core**
+
+- `AsNoTracking()` on every read-only query. Tracking on a 500-row list is pure overhead.
+- Project with `Select` into a DTO instead of loading entities and mapping in memory.
+- Multiple `Include`s of collections cause cartesian explosion — `AsSplitQuery()`.
+- Client-side evaluation: a `Where` the provider cannot translate can pull the table into memory. Modern EF throws instead, which is a gift — do not silence it with `AsEnumerable()` before the filter.
+- Never `await` a query inside a `foreach` over entities — batch it.
+- `ExecuteUpdateAsync`/`ExecuteDeleteAsync` for bulk changes rather than loading entities to modify them.
+
+**Prisma / TypeORM / Drizzle**
+
+- Prisma: `include` versus `select` matters — `select` only what the response needs; nested `include` on lists multiplies rows. Use `findMany` with `in` instead of a query per item, and `$transaction` for batches.
+- TypeORM: `relations` on a paginated query is a classic cartesian bug; use `QueryBuilder` with explicit joins and `take`/`skip` carefully, or paginate ids first. Eager relations are almost always a mistake.
+- Any ORM: repository methods that always fetch every relation "to be safe" are how a detail query becomes twelve.
+
+## Phase 6 — Transactions, locks and pools
+
+- **Transactions wrap a unit of work, not a request.** Never hold one open across an HTTP call, a queue publish, or user think-time.
+- Read-only transactions marked as such are cheaper; know your isolation level and why it is what it is.
+- **Deadlocks** are usually inconsistent lock ordering across code paths — acquire rows in a deterministic order (for example ascending id), keep transactions short, and retry the loser with backoff.
+- Long-running writes on hot rows serialize the system. Prefer optimistic locking (`@Version`, `rowversion`) over `SELECT ... FOR UPDATE` unless contention genuinely demands the pessimistic path.
+- Watch for lock waits directly: `pg_locks` plus `pg_stat_activity`, `sys.dm_tran_locks`, `V$LOCK`, `SHOW ENGINE INNODB STATUS`.
+- **Connection pool size is not "bigger is better".** More connections than the database has capacity for makes everything slower; a small pool with fast queries beats a large pool with slow ones. Set statement and idle-transaction timeouts so one stuck query cannot exhaust the pool. Check for pool exhaustion before blaming the query — the symptom is "everything is slow", not "this endpoint is slow".
+
+## Phase 7 — Verify and report
+
+Re-run the same measurement from Phase 1 and state the before and after: query time, row counts, statements per request. Confirm the plan actually changed shape — an index that exists but is unused fixed nothing. Check that the change did not slow writes elsewhere, and remove any diagnostic logging you enabled.
+
+Report in one short block: what was slow, why, what changed, measured improvement, and anything left on the table.
+
+## Rules
+
+1. Measure and name the offending query before changing anything; record the baseline.
+2. Count the queries per request first — an N+1 is not fixed by an index.
+3. Read an actual plan with real timings; trust actual rows and time, never cost.
+4. Change one thing at a time and re-measure.
+5. Check for an existing index before adding one; every index taxes writes.
+6. Never wrap an indexed column in a function, and never compare across mismatched types.
+7. `SELECT *` does not belong in application queries.
+8. Keyset pagination for anything deeper than a few pages.
+9. Transactions stay short and never contain a remote call; lock acquisition order is deterministic.
+10. Report before/after numbers, and revert any change that did not measurably help.
+

package/skill-sources/ingenium/skills/react-modern/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: react-modern
+description: Modern React and its frameworks, current as of August 2026 (React 19.2, React Compiler 1.0, Next.js 16) - server-first mental model with Server Components, Actions/useActionState/useOptimistic forms, use() for async, Compiler instead of manual memoization, framework selection (Next.js 16 vs React Router 7 framework mode vs TanStack Start v1 vs Vite SPA), Next.js 16 Cache Components with stable PPR and Turbopack, plus a stale-habit anti-pattern list and a freshness protocol that verifies current versions before locking decisions. Carries an existing-codebase protocol for brownfield projects - detect installed versions, match the repo's paradigm, modernize only as an explicit opt-in. Use when building, upgrading or optimizing React or Next.js apps, choosing a React framework or asking about current React best practices. Türkçe tetikleyiciler - "react'ta en güncel yöntem", "eski react projesinde çalış", "react 19 özellikleri", "next.js projesi kur", "next.js best practice", "server component nasıl kullanılır", "react compiler", "react projemi optimize et", "hangi react framework'ü", "en güncel react".
+---
+
+# React Modern (2026)
+
+You build React the way it works *now*, not the way tutorials taught it in 2022. The 2026 mental model: **server-first, compiler-optimized, actions-driven.** Old habits are the main source of bad modern React — this skill exists to replace them *in the code you write going forward*; existing codebases are protected by the brownfield protocol below.
+
+Always communicate with the user in their own language.
+
+## Freshness protocol
+
+Knowledge here is current as of **August 2026**: React 19.2 (Compiler 1.0 stable since Oct 2025), Next.js 16.x (Turbopack default, Cache Components + PPR stable), React Router 7, TanStack Start 1.0 (March 2026). Before locking framework/version decisions on a new project or upgrade, verify the current state at react.dev/blog and nextjs.org/blog — if reality has moved past this skill, reality wins and say so.
+
+## Existing codebase protocol (brownfield safety — read before touching an old project)
+
+The modern patterns in this skill describe **new code and greenfield decisions**. An existing project is governed by what it already is:
+
+- **Detect reality first**: React and framework versions from package.json and the lockfile; the paradigm from the code itself (class components? Pages Router? Redux? CRA?). Five minutes of reading beats one wrong assumption.
+- **Consistency beats modernity inside a codebase.** New code follows the repo's existing patterns — an Actions-and-RSC island pasted into a Pages Router app, or hooks idioms scattered through a class-component codebase, is a maintenance wound, not an upgrade.
+- **Feature-gate by installed version**: no `use()`/Actions below React 19, no `"use cache"`/PPR below Next 16, Compiler adoption is a project decision (supports back to 17, but opt-in) — never emit code the installed versions cannot run.
+- **Modernization is a proposal, never a side effect.** If upgrading would genuinely pay, say so separately — scope, win, risk, migration path — and execute it through the refactor-safe skill (behavior-preserving, incremental). Never modernize in passing while delivering a feature.
+
+## Stale habit → modern replacement (the core table)
+
+| 2022 habit | 2026 way |
+|---|---|
+| `useEffect` + `useState` for data fetching | Server Components / framework loaders; on the client TanStack Query; `use()` for passed promises |
+| `forwardRef` | `ref` is a normal prop now |
+| `memo`/`useMemo`/`useCallback` sprinkled everywhere | **React Compiler** memoizes automatically; write plain code |
+| Controlled-everything forms with submit handlers | **Actions**: `<form action={fn}>` + `useActionState` + `useFormStatus`; `useOptimistic` for instant feedback |
+| Global provider/store by default | Server state stays on the server or in a query cache; global client stores only for genuinely global client state |
+| SPA-by-default for everything | Framework decision below — SPA is one deliberate option, not the default |
+| Waterfall `await` chains in loaders | Parallel fetches + Suspense streaming |
+
+## React 19 in practice
+
+- **Actions**: any async function passed to `<form action>`, `formAction`, or transitions. `useActionState(fn, initial)` returns `[state, action, isPending]` — errors and pending become data, not choreography.
+- **`useOptimistic`**: render the expected result immediately, reconcile on settle — the default for likes, toggles, list-adds.
+- **`use(promise)`** suspends on a promise created *outside* render (server-passed or cached); `use(Context)` reads context conditionally. It does not replace a query cache.
+- **Refs**: plain prop; ref callbacks may return cleanup functions.
+- **Metadata**: `<title>`/`<meta>` hoist automatically from components (frameworks' metadata APIs still win for dynamic SEO).
+
+## React Compiler (default ON for new projects)
+
+- Auto-memoizes components and hooks at build time; works back to React 17; stable 1.0.
+- The contract: follow the Rules of React — pure render, no mutation of props/state, hooks called unconditionally. Enforce with `eslint-plugin-react-compiler`; code the compiler bails on is usually code with a real bug.
+- Delete manual `memo`/`useMemo`/`useCallback` in compiled code paths unless profiling proves a hot spot the compiler missed — keeping both is noise.
+
+## Server Components mental model (RSC)
+
+- **Server by default, client at interactivity boundaries.** A component becomes `'use client'` only because it needs state, effects, or browser APIs — and the boundary should sit as deep in the tree as possible (leaf-level islands, not page-level).
+- Server components fetch data next to where it renders (async/await directly in the component), ship **zero JS** for themselves, and can render client components; props crossing the boundary must be serializable.
+- Composition: server components pass *children* into client shells (`<ClientTabs>{serverContent}</ClientTabs>`) — interactivity wrapping server-rendered content.
+- RSC is a framework feature (Next.js; TanStack Start and React Router are adopting selectively) — in a plain Vite SPA this model simply doesn't apply; don't cargo-cult it there.
+
+## Framework decision (2026)
+
+| Situation | Pick |
+|---|---|
+| Full-stack app, SEO, content + app hybrid, team default | **Next.js 16** (App Router) |
+| SSR + data mutations with web-standards flavor (Remix lineage) | **React Router 7, framework mode** |
+| Client-heavy app wanting end-to-end type safety (routes, server functions) | **TanStack Start 1.0** (`createServerFn`, fully typed route tree) |
+| Internal tool, dashboard, game shell — no SEO need | **Vite + React SPA** (see web-kickoff) |
+
+State the choice and why in one paragraph; churn between frameworks mid-project is the real cost.
+
+## Next.js 16 best practices
+
+- **Turbopack is the default bundler** — dev and build; webpack-specific config is legacy.
+- **Cache Components model**: caching is now *explicit and opt-in*. `"use cache"` at the top of a page/layout/component caches its output; **PPR (stable)** serves the static shell instantly from CDN and streams dynamic holes as they resolve. Think in shells and holes: mark the cacheable frame, let personalized bits stream.
+- The old implicit fetch-caching confusion is gone — do not carry Next 13/14 cache folklore forward; cache what you *declare*, nothing else.
+- **Server Actions** for mutations: validate input with a schema (zod) at the top, mutate, then `revalidatePath`/`revalidateTag` — actions are public endpoints, treat them like API routes (auth checks inside the action).
+- `proxy.ts` replaces middleware for network-boundary logic.
+- Streaming discipline: `loading.tsx`/`Suspense` boundaries around slow subtrees; fetch in parallel (`Promise.all` or component-level fetches), never sequential awaits for independent data.
+- Platform pieces: `next/image`, `next/font`, route-level `error.tsx`/`not-found.tsx`; metadata API for SEO.
+
+## Data and state (client side)
+
+- Server state on the client → **TanStack Query v5** (the deka data-fetching skill covers patterns in depth — defer to it when installed).
+- Forms → actions first; React Hook Form + zod only when complex live client validation UX demands it.
+- Global client state → start with URL + component state; reach for zustand/jotai when prop-drilling genuinely hurts (see deka state-management when installed).
+
+## Performance, ranked by leverage
+
+1. Compiler on (free re-render elimination) → 2. RSC/PPR: ship less JS, stream the rest → 3. Suspense boundaries placed around actual slow spots → 4. `next/dynamic` for below-the-fold heavyweights → 5. Bundle/asset diet via the perf-audit skill. Measure before and after; folklore optimizations are how bundles grow.
+
+## Anti-patterns (2026 edition)
+
+`'use client'` at the page root "to be safe"; useEffect data fetching in framework apps; forwardRef in new code; manual memo carpets under the Compiler; sequential awaits for independent data; Server Action bodies without validation/auth; carrying Next 13/14 implicit-caching assumptions into 16; global stores holding server data; SPA-reflexes (client routing everything) inside an RSC app.
+