synorch 0.1.0

package/skill-sources/ingenium/skills/multiplayer-netcode/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: multiplayer-netcode
+description: Multiplayer and netcode for web games - choosing the right model per genre (lockstep, snapshot interpolation, client prediction with server reconciliation, rollback), transport selection (WebSocket vs WebRTC DataChannel vs WebTransport), authoritative server design, state sync and delta compression, lag compensation, determinism traps in JavaScript, anti-cheat basics and latency simulation testing. Use when adding multiplayer or online play to a game, syncing game state over the network, fixing lag/desync/rubber-banding, or designing rooms and matchmaking. Türkçe tetikleyiciler - "multiplayer ekle", "çok oyunculu yap", "online oyun", "netcode", "lag var", "oyuncular birbirini görsün", "state senkronizasyonu", "desync oluyor", "rollback".
+---
+
+# Multiplayer Netcode (Web Games)
+
+You design netcode that fits the game, not the fanciest technique. First, the honest warning you always give: **multiplayer multiplies scope 3–5×** — servers, sync, edge cases, cheaters, testing. The MVP is two players in one room with the simplest sync model that fits the genre; everything else comes after that works.
+
+Always communicate with the user in their own language.
+
+## Phase 1 — Pick the model by genre (the decision that decides everything)
+
+| Genre / need | Model |
+|---|---|
+| Turn-based (cards, board, strategy) | Plain request/response + authoritative state broadcast. No prediction needed. Start here whenever possible. |
+| Co-op casual, slow-paced (party games, .io-lite) | Server tick + **snapshot interpolation** (clients render ~100ms in the past, interpolating between snapshots) |
+| Action with player movement (shooters, arena) | Snapshot interpolation + **client prediction & server reconciliation** for your own player |
+| Precise competitive 1v1 (fighting, sports) | **Rollback** (GGPO-style) — requires a deterministic simulation |
+| Massive persistent worlds | Not an MVP. Interest management + sharding — scope this consciously later |
+
+State the choice and its consequences before writing any code.
+
+## Phase 2 — Transport
+
+- **WebSocket**: ordered, reliable (TCP). Perfect for turn-based and fine for most casual real-time. Weakness: head-of-line blocking — one lost packet stalls everything behind it.
+- **WebRTC DataChannel** (unreliable/unordered mode): UDP-like, what fast action games want; heavier setup (signaling, STUN/TURN — budget a TURN server, ~10–20% of connections need relay).
+- **WebTransport**: the modern UDP-like option over HTTP/3; check current browser/server support before committing.
+- Rule: **start with WebSocket**; move the *hot path only* (position updates) to unreliable transport when measurements demand it. Reliable events (chat, score, item pickup) stay on the reliable channel regardless.
+
+## Phase 3 — Authoritative server (non-negotiable for anything competitive)
+
+- The server owns truth: clients send **inputs/intents** ("move left", "play card 3"), never outcomes ("my HP is 100", "I won").
+- Validate every input server-side: legal move? plausible rate? in range? Client-side checks are UX, not security.
+- Hidden information (other players' hands, fog of war) never leaves the server — filter per recipient. Anything sent to a client is public to a cheater.
+- Fixed **tick rate** (10–30Hz casual, 60Hz competitive): simulate on tick, broadcast snapshots on tick or every Nth tick.
+- Room architecture first: rooms/lobbies with a max player count are how everything scales later. Frameworks: roll your own on `ws` (educational, fine for turn-based), **Colyseus** (rooms + state sync out of the box), or managed (Nakama, Hathora, PlayFab) when ops time is worth more than money.
+
+## Phase 4 — State sync mechanics
+
+- **Snapshots + interpolation**: server sends world state at tick rate; clients buffer ~2–3 snapshots and render other entities ~100ms in the past, interpolating. Smoothness beats freshness for everything that isn't you.
+- **Delta compression** when snapshots get fat: send changes vs last-acked snapshot; full snapshot on join/desync. Quantize floats (positions to cm, angles to bytes) before compressing.
+- **Client prediction (your own player)**: apply your input locally immediately; tag inputs with sequence numbers; server echoes last processed seq + authoritative state; on mismatch, rewind to server state and **replay unacked inputs** (reconciliation). Rubber-banding = reconciliation missing or broken.
+- **Lag compensation (hit detection)**: server rewinds targets to where the shooter *saw* them (timestamped shots) before resolving hits — otherwise high-ping players can't hit anything.
+- Interest management once rooms grow: send each client only what it can perceive.
+
+## Phase 5 — Rollback (only for the genres that need it)
+
+- Requires a **deterministic** simulation: same inputs → identical state on every client.
+- Loop: predict remote inputs (usually "same as last frame") → when real input arrives late, rewind to that frame, re-simulate to present. Needs: fixed timestep, fully serializable game state, sim decoupled from rendering, state save/load fast enough to re-run several frames in one frame budget.
+- **JS determinism traps**: `Math.random` → seeded PRNG (e.g. mulberry32) owned by the sim; `Date.now`/`performance.now` → tick counters only; unordered object/Map iteration feeding gameplay decisions → sort first; floating point is generally consistent same-engine but avoid `Math.sin/cos` accumulation drift — prefer integer/fixed-point for the critical sim state where feasible.
+- Desync detection: hash the game state every N ticks, compare between peers; on mismatch log the first diverging tick — that's your bug's address.
+
+## Phase 6 — Test like the network is hostile
+
+- Simulated latency/jitter/loss from day one (Chrome DevTools throttling; `tc netem` on Linux; toxiproxy) — netcode that only met localhost is untested. Test at 80ms, 150ms, 250ms with 1–3% loss.
+- Bots that send random-but-legal inputs at full rate: your load test and your fuzzer.
+- The two-browser-windows setup is the daily driver; add one real remote friend before believing anything ships.
+
+## Anti-patterns
+
+Trusting the client with outcomes; TCP-only for fast action then blaming "lag"; per-frame unthrottled sends (send on tick); no seq numbers ("it works on LAN"); building matchmaking before two friends can share a room code; retrofitting determinism for rollback after the sim is built (it's a rewrite — decide up front).
+

package/skill-sources/ingenium/skills/node-backend/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: node-backend
+description: Node.js backend engineering in TypeScript, current as of September 2026 (Node 24 LTS, NestJS 11, Express 5, Fastify 5) - choosing between NestJS and a plain Express/Fastify layout, a layered structure that survives growth (route, service, repository, no logic in the handler), async error handling that actually catches, validation at the boundary with Zod, config loaded and validated once at boot, graceful shutdown and the single-process realities (event loop blocking, unhandled rejections, memory), plus the tooling layer - pnpm workspaces, tsconfig that matches the runtime, ESM versus CJS, native test runner or Vitest, debugging and profiling. Framework recipes and NestJS specifics live in reference.md. Use when building, reviewing or debugging a Node/TypeScript API, choosing a Node backend framework or project structure, fixing async or performance problems in Node, or setting up Node tooling. Türkçe tetikleyiciler - "node backend yaz", "nestjs projesi", "express api", "fastify servisi", "typescript backend yapısı", "node performans sorunu", "async hata yakalanmıyor", "esm cjs sorunu", "pnpm workspace kur", "node projesini debug et".
+---
+
+# Node Backend
+
+You build Node services as boring, layered, typed programs: one process, an event loop you refuse to block, errors that cannot escape silently, and a boundary where every untrusted value is parsed before it reaches your code.
+
+Always communicate with the user in their own language.
+
+## Freshness protocol
+
+Current as of **September 2026**: Node 24 LTS (native TypeScript type stripping, stable `node --test`, built-in `fetch`, `node:sqlite`), NestJS 11, Express 5, Fastify 5, TypeScript 5.x, pnpm as the default package manager. Verify against nodejs.org/en/about/releases and the framework changelogs before locking a version decision — if reality moved past this skill, reality wins and say so.
+
+## Existing codebase protocol
+
+Detect before you write: Node version from `.nvmrc`/`engines`, package manager from the lockfile, `"type"` field and `tsconfig` module settings, framework from the dependencies, and the actual layering from two real route files. Match what exists. A Nest-style decorator module dropped into an Express codebase, or a service layer added to only one route, makes the codebase harder to read, not better.
+
+## Framework choice
+
+| Situation | Pick |
+|---|---|
+| Team backend, many modules, needs enforced structure and DI, likely to outlive its authors | **NestJS** — the opinionation is the product |
+| Small-to-mid service, throughput matters, you want to see every line of the pipeline | **Fastify** — schema-first, fast, sane plugin encapsulation |
+| Tiny service, glue, or an existing Express codebase | **Express 5** — universal, minimal, now with async error propagation |
+| Full-stack app already in Next.js/Nuxt | Its server layer first; add a separate service only when there is a real reason |
+
+Whatever the framework: the framework is delivery, not architecture. Business logic lives in plain functions and classes that can be tested without starting an HTTP server.
+
+## Structure that survives growth
+
+Organize **by feature**, not by technical role:
+
+```
+src/
+  orders/        orders.routes.ts  orders.service.ts  orders.repository.ts  orders.schema.ts
+  billing/       ...
+  shared/        config.ts  db.ts  logger.ts  errors.ts
+```
+
+- **The handler does four things**: parse input, call one service function, map the result, return. No queries, no branching business rules, no `if (user.role === ...)` policy checks inline.
+- **The service owns the use case** and knows nothing about HTTP — no `req`, no `res`, no status codes crossing into it. That single rule is what makes the logic testable and reusable from a job or a CLI.
+- **The repository owns data access.** SQL or ORM calls do not appear in services; swapping Prisma for raw SQL should touch one file per feature.
+- **Errors are typed domain values** (`NotFoundError`, `ConflictError`, `ValidationError`), mapped to HTTP status codes in exactly one place. Never `throw new Error("something")` and pattern-match on the message.
+
+## Validation and typing at the boundary
+
+- Every external input — body, query, params, headers, environment, third-party responses — is **parsed with Zod at the edge**, and the parsed type flows inward. `req.body as CreateOrderDto` is a lie the compiler cannot catch.
+- Derive TypeScript types from the schema (`z.infer`) so there is one source of truth, not a schema and an interface drifting apart.
+- `strict: true` in tsconfig, and no `any` at boundaries. `unknown` plus a parse is the honest alternative.
+- Validated config once at boot: parse `process.env` through a schema in `config.ts` and export a typed object. Reading `process.env.FOO` deep inside a module is how a service boots fine and dies on a code path nobody exercised.
+
+## Async and errors
+
+- **`async`/`await` everywhere, with every promise awaited or explicitly handled.** A floating promise is a lost error; enable `no-floating-promises` in ESLint.
+- Independent work runs with `Promise.all`; `Promise.allSettled` when partial failure is acceptable. Sequential `await`s for independent calls are latency you chose.
+- Express 5 forwards rejected promises from async handlers to the error middleware — but only if the handler is `async` and you did not swallow the rejection. Fastify and Nest handle it natively. One error handler at the end of the pipeline, always registered last.
+- Register `process.on('unhandledRejection')` and `uncaughtException` to log with context and exit; do not keep a process running in an unknown state.
+- **Add `AbortSignal`/timeouts to every outbound call.** `fetch` without a timeout hangs until the socket dies, and that is how one slow dependency saturates your event loop.
+- Retry only idempotent operations, with backoff and a cap.
+
+## Single-process realities
+
+- **Never block the event loop.** Synchronous crypto, big `JSON.parse` on megabyte payloads, `readFileSync` in a request path, and heavy loops all stall every concurrent request. Move CPU work to a `worker_threads` pool or a separate job; stream large payloads instead of buffering them.
+- **Stream, do not accumulate.** Building a 200k-row array in memory to send as JSON is a memory incident waiting for traffic; use streams or pagination.
+- **Graceful shutdown** on `SIGTERM`: stop accepting connections, finish in-flight requests with a deadline, close the DB pool, then exit. Without it, every deploy drops requests.
+- **Connection pools are configured, not defaulted.** Pool size, idle timeout and statement timeout are deployment decisions — see **query-tuning**.
+- Structured JSON logging with pino, one request-scoped child logger carrying a request id. `console.log` is not logging in a service.
+- Health endpoints (`/health/live`, `/health/ready`) and readiness that actually checks the database.
+
+## Tooling layer
+
+| Goal | Do this |
+|---|---|
+| Package manager | **pnpm**, with `packageManager` pinned in `package.json`; workspaces for a monorepo |
+| Node version | `.nvmrc` plus `engines` — one version across dev, CI and the image |
+| Module system | ESM (`"type": "module"`) for new projects; do not mix. In ESM, relative imports need explicit extensions |
+| TypeScript config | `strict`, `moduleResolution: "bundler"` or `"nodenext"` matched to the runtime, `isolatedModules`, `noUncheckedIndexedAccess` |
+| Dev loop | `node --watch` with type stripping for simple services; `tsx watch` when you need transpile-time features |
+| Build | `tsc` for libraries; `tsup`/`esbuild` for a bundled service image |
+| Tests | Native `node --test` for lean projects, **Vitest** when you want watch mode, mocks and coverage without ceremony |
+| Debug | `node --inspect-brk`, then attach from the editor. Faster than a console.log bisect, every time |
+| Profile | `node --cpu-prof` / `--heap-prof`, or Clinic.js — read a flame graph before optimizing anything |
+| Lint | ESLint flat config with `@typescript-eslint`, `no-floating-promises` and `require-await` on |
+
+## Data access
+
+Prisma for speed of development and migrations, Drizzle when you want SQL you can read and full type inference over it, raw `pg`/`postgres.js` for tight control. Whichever you pick: queries live in repositories, N+1 is a bug you look for on every list endpoint, and transactions wrap a use case — never a whole request. Load **query-tuning** for query and index work, **db-schema-craft** for modeling.
+
+## Testing
+
+- Domain logic tested as plain functions, no HTTP, no database.
+- Integration tests hit the real app through `supertest`/`app.inject()` against a **Testcontainers** database. SQLite standing in for PostgreSQL will pass tests production fails.
+- Each test owns its data and cleans up; shared mutable fixtures produce order-dependent suites that fail only in CI.
+
+## Framework recipes
+
+NestJS module/provider/DI specifics, Express 5 and Fastify pipeline recipes, and the graceful-shutdown and error-mapping snippets are in [reference.md](reference.md). Load it when you are actually writing framework-level wiring.
+
+## Rules
+
+1. Detect Node version, module system and framework before writing code; match the repo's layering.
+2. Handlers parse, delegate, map, return — no business logic and no data access in a route handler.
+3. Services never see `req`/`res`; HTTP concepts stop at the boundary.
+4. Every external input is parsed with a schema at the edge; no casting untrusted data.
+5. Config is validated once at boot and exported typed; no scattered `process.env` reads.
+6. No floating promises, no unhandled rejections, no `.then` chains mixed into `async` code.
+7. Every outbound call has a timeout or an `AbortSignal`.
+8. Nothing blocks the event loop in a request path; CPU work moves to a worker.
+9. Errors are typed domain values mapped to status codes in exactly one place.
+10. Graceful shutdown, structured logging and a real readiness check are part of the service, not extras.
+

package/skill-sources/ingenium/skills/node-backend/reference.md

@@ -0,0 +1,144 @@
+# Node Backend — Framework Recipes
+
+Load this when writing framework-level wiring. Everything here assumes the rules in SKILL.md still hold: handlers stay thin, services never see `req`/`res`, inputs are parsed at the edge.
+
+## NestJS 11
+
+### Module boundaries
+
+One module per feature, exporting only what other modules legitimately need. A module that exports every provider is a namespace, not a boundary.
+
+```ts
+@Module({
+  imports: [TypeOrmModule.forFeature([Order]), BillingModule],
+  controllers: [OrdersController],
+  providers: [OrdersService, OrdersRepository],
+  exports: [OrdersService],
+})
+export class OrdersModule {}
+```
+
+- Circular imports between modules mean the boundary is wrong. `forwardRef` is a patch for a design problem — fix the direction, extract a shared module, or move the shared concept down.
+- `@Global()` is almost always a mistake; the exception is a genuinely cross-cutting infrastructure module (config, logger) registered once at the root.
+
+### Providers and scope
+
+- Default provider scope is **singleton**. `Scope.REQUEST` propagates up the whole injection chain and destroys performance — use it only when you truly need per-request state, and prefer `AsyncLocalStorage` (via `nestjs-cls`) for request context instead.
+- Inject by class token wherever possible; string tokens are for dynamic and third-party wiring, and they lose type safety.
+- Custom providers (`useFactory`, `useClass`, `useValue`) are how you swap implementations per environment — not `if (process.env.NODE_ENV)` inside the service.
+
+### The pipeline, in order
+
+`Middleware → Guards → Interceptors (before) → Pipes → Handler → Interceptors (after) → Exception filters`
+
+| Concern | Belongs in |
+|---|---|
+| Is this caller allowed | **Guard** (`CanActivate`) |
+| Parse and validate the payload | **Pipe** (`ZodValidationPipe` or `ValidationPipe`) |
+| Timing, logging, response envelope, caching | **Interceptor** |
+| Turning a domain error into an HTTP response | **Exception filter**, registered once globally |
+| Raw request concerns (correlation id, body capture) | **Middleware** |
+
+Register the validation pipe and the exception filter globally in `main.ts`, never per-controller by copy-paste.
+
+```ts
+app.useGlobalPipes(new ZodValidationPipe());
+app.useGlobalFilters(new DomainExceptionFilter());
+app.enableShutdownHooks();
+```
+
+### Validation with Zod
+
+Define the schema next to the feature and derive the DTO type from it; do not maintain a `class-validator` DTO *and* a schema.
+
+```ts
+export const createOrderSchema = z.object({
+  customerId: z.uuid(),
+  lines: z.array(z.object({ sku: z.string().min(1), qty: z.int().positive() })).min(1),
+});
+export type CreateOrder = z.infer<typeof createOrderSchema>;
+```
+
+If the project already standardizes on `class-validator`, stay with it — consistency wins.
+
+### Configuration
+
+`ConfigModule.forRoot({ validate, isGlobal: true, cache: true })` with a schema-based `validate` function, then inject a typed config service. Never read `process.env` inside a provider.
+
+### Testing
+
+- Unit: instantiate the service directly with fakes. `Test.createTestingModule` for one class is ceremony.
+- Integration: build the real module graph, override only the boundary providers, hit it with `supertest`. Use Testcontainers for the database.
+- `app.close()` in `afterAll`, or the suite leaks handles and hangs CI.
+
+### Common Nest mistakes
+
+Business logic in controllers; request-scoped providers used casually; `forwardRef` instead of fixing a boundary; entities returned straight from controllers; `@Global()` on feature modules; catching errors in the service to return `null`, which erases the reason the operation failed.
+
+## Fastify 5
+
+- **Schema-first**: attach JSON Schema for body, querystring, params and response. Response schemas are not documentation — Fastify uses them to serialize, which is both faster and a guarantee you never leak an internal field.
+- Use `fastify-type-provider-zod` (or the TypeBox provider) so one schema gives you validation, serialization and inference.
+- **Plugins encapsulate.** Anything registered inside a plugin is invisible outside it; to share a decorator or hook, wrap with `fastify-plugin`. Most "my decorator is undefined" bugs are this rule working as designed.
+- Hooks map cleanly to concerns: `onRequest` for auth, `preValidation` for shaping input, `preHandler` for authorization, `onSend` for response mutation, `onError` for logging.
+- `setErrorHandler` once, at the root, mapping domain errors to status codes.
+- Fastify ships pino: use `request.log`, which already carries the request id.
+
+```ts
+app.get('/orders/:id', { schema: { params: idParams, response: { 200: orderResponse } } },
+  async (req) => toResponse(await orders.byId(req.params.id)));
+```
+
+## Express 5
+
+- Async handlers that reject now reach the error middleware — no `express-async-handler` wrapper needed. Non-promise callbacks still do not; call `next(err)`.
+- The error handler is the **last** `app.use`, takes four arguments, and is the only place that turns a domain error into a status code.
+- Path matching changed in 5: no bare `*` wildcards (`/*` becomes `/*splat`), and optional-parameter syntax is stricter. This is the most common Express 4→5 upgrade break.
+- Order is behavior: security headers (`helmet`) → cors → body parsers with an explicit `limit` → routes → 404 handler → error handler.
+- `express.json({ limit: '1mb' })` — an unbounded body parser is a denial-of-service surface.
+- Router per feature (`ordersRouter`), mounted at one path. A 600-line `app.ts` is the failure mode Express invites.
+
+## Error mapping (any framework)
+
+```ts
+export class DomainError extends Error {
+  constructor(message: string, readonly code: string, readonly status: number) { super(message); }
+}
+export class NotFoundError extends DomainError {
+  constructor(what: string) { super(`${what} not found`, 'not_found', 404); }
+}
+```
+
+One mapper at the boundary turns these into an RFC 9457 body:
+
+```json
+{ "type": "about:blank", "title": "not_found", "status": 404, "detail": "Order not found", "instance": "/orders/42" }
+```
+
+Unknown errors become a 500 with a correlation id in the body and the full stack in the log — never the stack in the response.
+
+## Graceful shutdown
+
+```ts
+const shutdown = async (signal: string) => {
+  logger.info({ signal }, 'shutting down');
+  const timer = setTimeout(() => process.exit(1), 10_000).unref();
+  try { await app.close(); await db.end(); clearTimeout(timer); process.exit(0); }
+  catch (err) { logger.error({ err }, 'shutdown failed'); process.exit(1); }
+};
+for (const s of ['SIGTERM', 'SIGINT']) process.on(s, () => void shutdown(s));
+```
+
+The hard-exit timer matters: without it a hung connection makes the pod hang until the orchestrator kills it, which looks exactly like a crash.
+
+## Monorepo layout (pnpm workspaces)
+
+```
+pnpm-workspace.yaml
+apps/api/          the service
+packages/contracts/  Zod schemas + inferred types shared with the frontend
+packages/config/     tsconfig + eslint bases
+```
+
+`packages/contracts` is the highest-leverage package in a full-stack repo: the API validates with the same schema the frontend's client types are inferred from, so a contract change breaks the build instead of production. Use `workspace:*` for internal dependencies and keep a single TypeScript base config.
+

package/skill-sources/ingenium/skills/perf-audit/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: perf-audit
+description: Measurement-first web performance audit and optimization - Core Web Vitals (LCP, INP, CLS) diagnosis, Lighthouse and DevTools profiling, bundle size diet (code splitting, tree shaking, dependency replacement), image/font/third-party optimization, caching and network strategy, and runtime jank hunting. Use when a site or app feels slow, the bundle is too big, Core Web Vitals fail, load times are bad, or asked to audit or improve web performance. Türkçe tetikleyiciler - "site yavaş", "performans denetimi yap", "bundle'ı küçült", "sayfa geç açılıyor", "web vitals düzelt", "performansı iyileştir", "neden bu kadar yavaş yükleniyor".
+---
+
+# Perf Audit
+
+You are a web performance engineer. Prime directive: **measure, change one thing, measure again.** No cargo-cult optimization — every recommendation is tied to a number you observed, and every fix is verified by the same number moving.
+
+Always communicate with the user in their own language.
+
+## Phase 1 — Baseline before touching anything
+
+- Run Lighthouse in mobile mode with throttling (that is where users suffer); record LCP, INP/TBT, CLS, transfer sizes.
+- Pull field data if it exists (CrUX, analytics RUM) — lab and field can disagree; field wins.
+- Take a DevTools Performance trace of the complained-about interaction.
+- Identify the ONE metric behind the user's actual complaint ("slow to open" → LCP/TTFB; "laggy when I click" → INP; "things jump around" → CLS; "slow after load" → runtime). That metric is the audit's spine.
+
+## Phase 2 — Diagnose by metric
+
+**LCP** (slow first paint of the main content):
+- Find what the LCP element actually is (Lighthouse tells you) — optimize *that*, not everything.
+- Walk the chain in order: TTFB (server/CDN/redirects) → render-blocking CSS/JS → resource load time (is the hero image discoverable early? `fetchpriority="high"`, preload, no lazy-loading the LCP image) → client render (SSR/streaming vs client-only rendering).
+
+**INP** (slow response to interaction):
+- Performance trace → long tasks (>50ms) on the main thread; find who owns them.
+- Usual suspects: hydration cost, heavy event handlers, synchronous state cascades, third-party scripts. Fixes: break up tasks (`scheduler.yield`/`setTimeout` chunking), defer non-critical JS, debounce, move compute to a Web Worker.
+
+**CLS** (layout shift):
+- Images/embeds without dimensions → always set width/height or aspect-ratio.
+- Late-injected banners/ads → reserve the space.
+- Web font swap reflow → see fonts below.
+
+## Phase 3 — Bundle diet
+
+- Visualize first: source-map-explorer, rollup-plugin-visualizer, or the framework's analyzer. Name the top 5 offenders by size.
+- Route-level code splitting; dynamic-import anything below the fold or behind interaction (modals, editors, charts).
+- Replace heavyweights with evidence: check bundlephobia-style cost before/after (classic wins - moment→dayjs, lodash→per-method or native, big date/chart/icon libraries → scoped imports).
+- Tree-shaking blockers: barrel files re-exporting everything, packages without `sideEffects: false`, CommonJS-only deps.
+- Kill duplicate dependencies (two versions of the same lib) — check the lockfile.
+
+## Phase 4 — Assets
+
+- **Images**: modern formats (AVIF/WebP with fallback), responsive `srcset/sizes`, lazy-load everything *except* the LCP image, CDN resizing — never ship a 4000px original into a 400px slot.
+- **Fonts**: woff2 only, subset to used glyphs, self-host, `font-display: swap` (or `optional` for non-brand text), preload the one critical font, cap families × weights.
+- **Third parties**: inventory them with a trace; defer what you can, facade-pattern heavy embeds (YouTube, maps, chat widgets load on interaction), delete what nobody remembers adding.
+
+## Phase 5 — Network and caching
+
+- Hashed immutable static assets with long-lived `Cache-Control`; correct caching on HTML (short/no-store) vs assets (immutable).
+- Compression (brotli), HTTP/2+, `preconnect` to critical origins, no redirect chains on the critical path.
+
+## Phase 6 — Runtime jank (after load)
+
+- Long lists → virtualization.
+- Layout thrash → batch DOM reads and writes; never interleave in a loop.
+- Animations → transform/opacity only (hand off to the motion-craft skill for animation work).
+- Heavy compute → Web Worker. Canvas/game loops → stay inside the 16.6ms frame budget; no allocations per frame.
+- React-specific re-render storms → defer to the deka-engineering-react performance-optimization skill if installed; this audit stays at the platform level.
+
+## Phase 7 — Report
+
+Before/after table per metric, what was changed and why, and the ranked list of remaining opportunities with expected impact (high/medium/low) so the user can stop at the right point of diminishing returns.
+
+## Rules
+
+- One change per measurement cycle when verifying; batched fixes get batched credit and hide regressions.
+- Never trade correctness or accessibility for speed silently — flag the trade-off.
+- Do not chase a 100 score for its own sake; chase the user-felt metric.
+

package/skill-sources/ingenium/skills/pixel-art-assets/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: pixel-art-assets
+description: Create pixel art game assets that read as human-crafted, not AI-generated - style bible first (locked palette with hue-shifted ramps, one outline rule, one light source, one pixel density), craft fundamentals (silhouettes, clusters, hand anti-aliasing, dithering discipline), three production routes (hand-drawn in Aseprite, palette-constrained scripted generation, diffusion output rescued via downscale-quantize-handfix with the bundled px.py tool), recipes per asset type (characters, animation frames, tilesets, UI, VFX) and engine-ready export. Use when creating, generating, cleaning or reviewing pixel art sprites, tiles, animations, icons or any game asset, or building a consistent asset set. Türkçe tetikleyiciler - "pixel art asset üret", "sprite çiz", "tileset yap", "karakter sprite'ı oluştur", "ai ile asset üret", "asset'i temizle", "insan çizmiş gibi dursun", "assetler tutarlı olsun", "animasyon frame'leri".
+---
+
+# Pixel Art Assets
+
+You produce pixel art that reads as deliberately crafted by a human. The human-made look is not a filter — it is **constraints applied consistently**: one pixel grid, one locked palette, one outline rule, one light source, across every asset in the set. AI output becomes raw material that gets disciplined into the system, never the final word.
+
+Always communicate with the user in their own language.
+
+## Why AI pixel art looks AI (the tell catalog)
+
+Diagnose these before fixing anything — three or more and the asset reads generated:
+
+- **Fake pixel grid**: "pixels" of varying sizes and alignments (diffusion models paint pixel-*style*, not pixels).
+- **Color flood**: hundreds of colors where an artist uses 16; muddy gradients inside what should be flat clusters.
+- **Straight-darker shadows**: shading that only darkens the same hue — no hue shift (the single loudest tell).
+- **No committed light source**; over-rendered noise and melty, almost-symmetric detail.
+- **Soft alpha edges** and glow halos around sprites (sticker look).
+- **Style drift**: each asset in the set slightly different in outline, saturation, density or proportion.
+
+## Phase 0 — The style bible (before ANY asset exists)
+
+Write `assets/STYLE.md` in the game repo and re-read it at the start of every asset session. Template:
+
+```markdown
+# <Game> Pixel Art Style Bible
+- Grid: tiles 16x16, characters 32x32 (body ~24px tall), items/icons 16x16, UI at 1x
+- Palette: <name/link or hex list - 16-32 colors TOTAL, locked>
+- Ramps: 3-5 shades per material; shadows shift cool (toward blue/violet),
+  highlights shift warm (toward yellow); saturation peaks in midtones
+- Outline: <pick ONE - full black / selout (colored per neighbor) / lineless>
+- Light: top-left, always
+- Proportions: <e.g. 1:1 head-to-body chibi at 32px; 3/4 top-down view>
+- Alpha: binary (0 or 255) - no soft edges, no glows
+- Dithering: <e.g. sparse checkerboard for large gradients only / none>
+- AA: interior-only, hand-placed, max 1px against outline
+```
+
+Palette guidance: start from a proven palette (Lospec is the library of record — e.g. a 16–32 color general palette) or build ramps by hand. Fewer colors is a *feature*: constraints create the crafted look.
+
+## Craft fundamentals (what your hands enforce)
+
+- **Silhouette first**: fill the sprite solid black; if it isn't readable at 1x in-game size, no amount of detail will save it. Design silhouette → big shapes → detail, in that order.
+- **Clusters, not confetti**: group pixels into meaningful shapes of one ramp step; scattered single-pixel noise reads as texture spam. Every pixel is a decision.
+- **Pixel-perfect lines**: no doubled pixels on diagonals, consistent staircase rhythm on curves (1-2-3 step progressions, not 1-3-1).
+- **Hue-shifted ramps**: in HSV terms per step darker — value down, hue rotated 8–20° toward cool; per step lighter — value up, hue toward warm; saturation highest in the middle of the ramp. This is 80% of "looks hand-painted".
+- **Hand anti-aliasing**: a few midtone pixels softening hard interior curves — never automatic AA, never against transparent edges.
+- **Dithering with intent**: checkerboard/Bayer for large gradient fields (sky, vignette) and retro flavor; modern clean styles use almost none. Random dithering never.
+- **Anti-patterns**: pillow shading (concentric rings of light regardless of light source), banding (parallel ramp lines hugging an outline), outline-color inconsistency, mixed pixel densities in one scene (a 1x sprite on a 2x background breaks the world).
+- **Readability hierarchy**: gameplay-critical elements get the strongest value contrast and the most saturated colors; backgrounds recede (lower contrast, cooler, desaturated). Reserve one accent color for interactables.
+
+## Three production routes (choose per asset)
+
+| Asset | Route |
+|---|---|
+| Player, key characters, hero animations | **A — hand-drawn** (highest craft, it's the face of the game) |
+| Tiles, props, items, icons, UI, particles | **B — scripted generation** (perfect grid + palette by construction) |
+| Concept art, mood refs, large backgrounds | **C — diffusion + rescue** (raw material, never final) |
+
+**Route A — Aseprite.** Master files are `.aseprite` in `assets/src/`. Work in Indexed mode with the style-bible palette loaded (colors outside the palette become *impossible*). 1px pencil, shading ink for ramp work, onion skin for animation, tags per animation, export via CLI for repeatability.
+
+**Route B — scripted (true pixel art from code).** For grid-friendly assets, write a small script (Python/Pillow or JS canvas) that draws on the exact grid with the style-bible palette as named constants — output is pixel-perfect by construction, and variants are a loop (6 grass tiles with shuffled detail placement). Iterate: generate → upscale preview (8x) → adjust script → regenerate. This beats diffusion for consistency on simple assets and is fully reproducible.
+
+**Route C — diffusion rescue pipeline.** When using an image model for complex raw material:
+1. Generate large, one subject, plain background, strong silhouette; ask for flat shading.
+2. Downscale to the true grid and lock to palette with the bundled tool: `python "${CLAUDE_SKILL_DIR}/scripts/px.py" quantize raw.png --grid 32x32 --method box --palette assets/palette.hex` (BOX averaging then palette-snap survives fake-grid noise better than nearest).
+3. **The mandatory hand pass** — this is where "human-made" happens: fix the silhouette, re-shade with the committed light source and hue-shifted ramps, apply the outline rule, merge noise into clusters, binarize alpha, re-do face/hands (AI melts them at small sizes).
+4. Audit next to existing assets (contact sheet below). If the hand pass exceeds drawing from scratch — common for small sprites — draw from scratch; diffusion earns its keep on concepts and big backgrounds, rarely on a 16px item.
+
+## Recipes per asset type
+
+- **Characters**: fix the canvas box and ground line; ≤10 colors per character; design limbs as separable clusters (animation needs them); consistent view angle (side or 3/4 top-down) across the whole cast; darkest outline value reserved for silhouette edge.
+- **Animation**: key poses first, inbetweens after. Frame budgets that read well: idle 4–6, walk/run 6–8, attack 3–5 plus anticipation and follow-through, hit/death 4–6. Squash & stretch in pixel terms (compress the cluster, don't scale the sprite). Sub-pixel illusion: shift interior clusters and AA one frame before the outline moves. Keep pivot/feet on the ground line in every frame; tag animations in Aseprite and export sheet + JSON.
+- **Tilesets**: prove seamlessness by tiling 3×3 and offsetting by half a tile; make 2–4 variants of any large-area tile (grass, floor) to kill visible repetition; terrain edges via the engine's autotile template (Godot terrains, Tiled — the 47-tile blob covers all cases); tiles stay lower-contrast than sprites; atlas with 1–2px extrusion (see pixel-game-dev on bleeding).
+- **UI**: 9-slice panels (corners fixed, edges repeat); a real pixel font at integer sizes only; icons on one shared grid with one shared outline rule; UI pixel density matches the game (no 1x game with 4x-smooth UI).
+- **VFX**: few frames (4–8), big readable shapes, ramps that end bright (white/near-white last frame) for additive blending; smear frames beat motion blur.
+
+## QA ritual (every asset, every set)
+
+1. View at **1x in-game size** (the only truth) and at 4–8x (the editing view). Judge at 1x.
+2. Palette audit: `px.py palette sprite.png` — any color outside the style bible is a bug.
+3. Light/outline/density check against STYLE.md.
+4. Set consistency: `px.py sheet assets/sprites --scale 4` → one contact sheet; drift is obvious side by side.
+5. In-engine screenshot at real resolution — rendering settings can undo everything (see pixel-game-dev's pixel-perfect rules).
+
+Bundled tool: [scripts/px.py](scripts/px.py) (`pip install pillow`) — commands: `quantize` (downscale + palette lock + binary alpha), `upscale` (integer preview), `palette` (color audit), `sheet` (contact sheet). Ship 1x PNGs; previews are for review only.
+
+Pairs with: **game-design** (the MVP asset list — don't craft 200 assets before the rectangle test passes), **pixel-game-dev** (rendering, atlases, integration), **human-made-design** (menus/marketing pages around the game).
+