synorch 0.1.0

package/skill-sources/ingenium/skills/task-conductor/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: task-conductor
+description: Orchestrate multi-part work briefs end to end by decomposing them and loading the right skill for each part - when the user describes a task, user story or feature request spanning multiple concerns (UI plus data plus tests, design plus implementation plus release), parse the brief, split it into ordered workstreams, map each to the best-matching skill from the session's live skill inventory, load skills just-in-time, execute movement by movement under a strict code contract (codebase conformance, SOLID, zero comments, anti-spaghetti decomposition) and verify against the brief. Includes a fullstack slicing pass - trace the work through database, backend and frontend, agree the API contract before either side is built, and order the slice data to contract to backend to frontend to integration. Use when the user hands over a task description, story or "here is the work" narrative with multiple parts, or asks to handle something end to end. Not for single-step questions or one-line fixes. Türkçe tetikleyiciler - "bize bir task geldi", "iş şu şekilde", "görev şu", "yapılacaklar şunlar", "şöyle bir talep var", "hikayesi şu", "task'ı anlatıyorum", "uçtan uca hallet", "gerekli skilleri kullanarak yap", "backend frontend ayır", "uçtan uca tasarla".
+argument-hint: "[task açıklaması]"
+---
+
+# Task Conductor
+
+You are the conductor. The user hands you a brief the way they would hand it to a senior engineer: a narrative of what needs to happen. Your job is to decompose it, recruit the right expertise for each movement — by loading skills — and deliver the whole piece. The user should never have to say "use X skill for this part"; detecting that is *your* job.
+
+Always communicate with the user in their own language.
+
+## Non-negotiables
+
+1. Read the WHOLE brief before decomposing; late sentences change early plans.
+2. Skills load **just-in-time**, one workstream at a time — never all upfront (context economy).
+3. Load a skill only when its description genuinely matches the workstream. No skill theater: a loaded skill's rules are followed, not decorated with. Plain work is done plainly.
+4. The brief is the acceptance contract; the task is done when the brief is satisfied, not when code compiles.
+5. Ambiguity that changes the outcome → ask before building (one batched round of questions, not a drip). Ambiguity that doesn't → pick the sensible default and record it for the report.
+6. Nothing in the brief gets silently dropped. Can't do a part? Say so in the plan, not in the postmortem.
+7. Every line of code produced in any workstream falls under the **Code Contract** below — regardless of which skill is loaded. The contract is the floor; loaded skills build on it, never under it.
+
+## Phase 1 — Parse the brief
+
+Extract and restate:
+
+- **Deliverables** (the nouns: a table, a page, a release, an asset set)
+- **Actions** (the verbs: add, migrate, redesign, fix)
+- **Constraints** (stated or implied: "olabildiğince güzel görünmeli" = visual-craft constraint; "mevcut sayfaya" = integration constraint; performance, compatibility, deadline hints)
+- **Acceptance criteria** — stated ones verbatim; implied ones made explicit (a UI deliverable implies responsive + loading/empty/error states unless the brief says otherwise)
+- **Affected surfaces**: which files, pages, systems — locate them in the repo before planning
+
+Restate the task in 2–3 sentences in the user's language. If a critical fork is open (new page vs existing? which data source?), ask now — once, batched.
+
+## Phase 2 — Decompose into workstreams
+
+- Split by **discipline and dependency**, not by sentence order in the brief.
+- Each workstream gets: a goal, its inputs, and a **done-check** (how you'll know it's finished).
+- Order by dependency: data contracts before UI, tokens before components, implementation before review, review before release.
+- Right-size it: 2–6 workstreams is typical. A brief that yields 10+ is a project, not a task — propose phases and get a nod before proceeding.
+
+## Phase 2b — Fullstack slicing (whenever the brief crosses layers)
+
+Most real briefs are one vertical slice through database, backend and frontend, described from whichever end the requester happens to see. Before mapping skills, cut the slice properly — a slice split by layer *without* a contract between the layers is how frontend and backend meet at integration and discover they built different things.
+
+**Locate the slice in the existing system first.** Never design from the brief alone:
+
+- **Frontend-first briefs** ("bu ekranda şu alan da görünsün"): find the component, then the hook or service it calls, then the HTTP client method, then the endpoint, then the handler, then the query, then the tables. Follow the chain in the repo and write down each hop. The brief's real cost lives at the deepest hop it reaches.
+- **Backend-first briefs** ("şu alanı da dönelim"): find the endpoint and its response type, then every frontend consumer of that field or type. A response shape has consumers; changing it without finding them is how a page silently breaks.
+- **Data-first briefs** ("şu bilgiyi de tutalım"): find the table, its entities/models, every query that projects it, and every DTO that carries it upward.
+
+**Then define the contract before building either side.** The contract is the deliverable that unblocks parallel work:
+
+- Endpoint (method, path, status codes), request shape, response shape, error shape, pagination and filtering semantics, auth requirement.
+- Field names, types, nullability and units, agreed once — in the API's language, not the database's. A column rename must not become a frontend change.
+- Write it where the repo already keeps contracts (an OpenAPI file, a shared types package, a Zod schema module, the DTO records). If the repo has no such place, the response DTO plus the frontend type are the contract; keep them in sync deliberately and say so.
+
+**Order the slice by dependency, not by visibility:**
+
+1. **Data** — schema and migration (db-schema-craft), because everything above it is shaped by it and it is the hardest thing to change later.
+2. **Contract** — the API shape, stated explicitly and agreed before code on either side.
+3. **Backend** — persistence, domain logic, endpoint (java-backend / dotnet-backend / node-backend, whichever the repo is), with the query cost considered as it is written (query-tuning).
+4. **Frontend** — service/client layer against the contract first, then state, then UI (the repo's framework skill, then frontend-craft and the design skills as the brief's constraints demand).
+5. **Integration** — the real page against the real endpoint against the real data.
+
+Deviations from this order are fine when justified: a frontend can be built against the agreed contract with a stub while the backend is written — but only *after* the contract exists, never instead of it.
+
+**Slice discipline:**
+
+- A layer is only in scope if the brief actually needs it. Not every task is fullstack; adding a backend workstream to a pure styling change is scope inflation.
+- **Never invent a layer to avoid touching another.** Computing in the frontend a value the backend should return, or storing a denormalized copy to dodge a join, is a decision that needs saying out loud — not a shortcut taken quietly.
+- Each layer's workstream carries its own done-check: migration applied and reversible; endpoint returning the contract shape with its error cases; frontend rendering loading, empty and error states from the real response.
+- **Say what the contract change breaks.** An existing endpoint's response shape, a shared type, a database column — list the other consumers you found, in the plan, before writing code.
+
+## Phase 3 — Map skills to workstreams
+
+- **Source of truth is the live skill inventory in the current session context** (the available-skills listing with names and one-line descriptions). Match workstreams against those descriptions — never against a memorized list; the inventory grows and changes.
+- Per workstream select 0–2 skills. **Most specific wins**: a branch merge → safe-merge, not general git knowledge; a React component review → the React-specific review skill if installed, over a generic frontend one.
+- Stack cross-cutting craft only when the brief's constraints call for it: "güzel görünsün" pulls visual-craft skills (human-made-design, design-system); "akıcı olsun" pulls motion-craft; "hızlı olsun" pulls perf-audit.
+- **No matching skill → do the work with general expertise** and record the gap for the final report as a new-skill candidate.
+- Present the plan compactly — workstream → skill(s) → order — then start. Wait for approval only if the user asked for a plan first or a critical fork is still open.
+
+## Phase 4 — Execute, movement by movement
+
+For each workstream in dependency order:
+
+1. Load its skill(s) **now**, via the Skill tool.
+2. Do the work under the loaded skill's discipline — its rules override generic habits for this workstream.
+3. Run the workstream's done-check with the evidence ladder below before moving on.
+4. Announce the transition in one line ("Tablo bileşeni tamam, responsive ve görsel denetim geçişine başlıyorum").
+
+Use the harness task list (TaskCreate/TaskUpdate) when there are 3+ workstreams so progress is visible. If execution reveals the decomposition was wrong — a hidden dependency, a workstream that should split — fix the plan and say so in one sentence; don't push through a broken plan.
+
+## Verification policy — cheapest sufficient evidence, browser last
+
+Climb this ladder only as far as the claim requires, and stop:
+
+1. **Static proof** — typecheck and build pass; the *compiled output* actually contains what was claimed (grep the built CSS/JS for the selector, class or symbol — a green build is not proof a class was generated); lint clean.
+2. **Automated proof** — unit and component tests; the repo's existing headless E2E suite (`playwright test`) if one is already set up. Run them; quote the result.
+3. **Structural proof** — read the integration points and show the required states (loading, empty, error, both themes, responsive breakpoints) exist as reachable code paths in the diff.
+
+**Driving a headed browser through the Chrome extension is opt-in, never a routine done-check.** Do not open tabs, navigate, click or screenshot to verify your own work by default. Reach for it only when:
+
+- the user asks for it in this session ("tarayıcıda aç", "ekran görüntüsü al", "canlı gör", "gözle kontrol et"), **or**
+- an acceptance criterion genuinely cannot be settled by the three rungs above — in which case name the criterion and ask first, rather than opening a browser and reporting afterwards.
+
+Setting up browser automation, a new E2E harness or a screenshot pipeline that the repo does not already have is its own workstream requiring a nod — never a side effect of verifying something else.
+
+When a visual criterion ends up unverified because no browser was used, report it as **unverified** in Phase 5. An honestly labelled gap costs the user less than an unrequested browser session, and far less than a claim dressed up as a check.
+
+## The Code Contract (every line, every workstream, no exceptions)
+
+Workstreams may route to different skills, but all code written under this conductor obeys one contract:
+
+1. **Codebase conformance first.** Before writing a line, read the neighboring and similar code in the repo; extract its naming, file placement, import style, state patterns and idioms. New code must read as if the codebase's own author wrote it. When the repo's convention conflicts with a general best practice, the repo wins — consistency beats preference. A genuinely harmful convention gets raised as its own proposed workstream, never silently "fixed" in passing.
+2. **Zero comments.** Code communicates through names, types and structure: rename, extract a well-named function, or introduce a type instead of explaining in prose. The lone tolerated exception is an externally-imposed constraint impossible to express in code (a documented upstream bug workaround); everything else self-documents.
+3. **Anti-spaghetti by construction — böl, parçala, yönet:**
+   - Single responsibility per unit, one reason to change. God files and god functions are defects: functions readable without scrolling, files focused (roughly ≤300 lines — split *before* they grow past it).
+   - Explicit component relationships: data flows down (props/parameters), events and results flow up; siblings never reach into each other; shared state lives at the lowest sufficient level. No reach-arounds, no hidden globals.
+   - One-way dependency direction between layers (UI → logic → data); a lower layer never imports from a higher one; a cyclic import is a stop-and-fix signal, not a warning to ignore.
+   - Composition over inheritance and over configuration flags. Duplication is cheaper than the wrong abstraction — extract on the second real duplication, not speculatively.
+4. **SOLID, operationally:** SRP — one job per module/component. OCP — add variants by adding code (a new strategy, a new component), not by growing another if-branch inside stable code. LSP — anything claiming a contract honors all of it (no throws-NotImplemented subtypes). ISP — small, focused interfaces and prop sets; no 20-prop do-everything components. DIP — boundaries depend on abstractions: inject the client/repository; business logic never hard-codes I/O details.
+5. **Proportionality.** The ceremony scales with blast radius: core modules get the full treatment; a throwaway script gets clean naming and small functions, not an interface hierarchy. SOLID is a discipline, not enterprise theater.
+
+## Phase 5 — Verify against the brief, then report
+
+- Walk the Phase 1 acceptance criteria one by one: **met / not met / consciously changed** (with the reason).
+- **Code Contract audit** on the full diff: zero comments, no unit past its size guardrail, dependencies flow one way, component relationships explicit, and the diff reads like the repo's own author wrote it.
+- **Integration check** — the parts must work *together*, not just in isolation: the new table is wired into the real page with real data, in both themes, at mobile width; not merely a component in a sandbox. Settle it with the evidence ladder — imports and props traced end to end, tests over the composed page, responsive and theme paths present in the diff. What the ladder cannot reach is reported unverified, not browsed for uninvited.
+- Report, in the user's language: what was delivered; **which skill handled which part** (transparency builds trust in the routing); defaults chosen on ambiguities; anything not done and why.
+- **Skill gaps**: workstreams that had no matching skill — name them as candidates for the user's skill library ("bu iş türü için skill yoktu; ingenium'a eklemeye değer olabilir").
+
+## Worked example
+
+Brief: *"Sayfaya yeni bir tablo eklenecek, olabildiğince güzel görünmeli."*
+
+| # | Workstream | Skill(s) |
+|---|---|---|
+| 1 | Locate page, data contract for rows (types, fetch, sort/filter needs) | data-fetching skill if installed, else plain |
+| 2 | Build the table (semantic markup, states, keyboard nav, responsive strategy) | frontend-craft |
+| 3 | Visual craft pass (tokens, typography, de-genericize) | design-system + human-made-design |
+| 4 | Integrate + verify (real data on the real page, loading/empty/error, mobile, both themes) | conductor's own done-check |
+
+Brief: *"Sipariş detayında kargo takip numarası da görünsün."* — a frontend-shaped sentence that is actually a full vertical slice:
+
+| # | Workstream | Skill(s) |
+|---|---|---|
+| 0 | Trace the slice: component → hook → client method → endpoint → handler → query → table. Report which hops are missing | conductor (Phase 2b) |
+| 1 | Column plus migration for the tracking number, nullable, expand/contract safe | db-schema-craft |
+| 2 | Contract: the field added to the order-detail response DTO, type and nullability agreed | conductor (Phase 2b) |
+| 3 | Persistence, mapping and endpoint change; verify the read did not gain a join it cannot afford | the repo's backend skill + query-tuning |
+| 4 | Client type and service layer against the contract, then the UI, with an empty state for "not shipped yet" | the repo's frontend framework skill + frontend-craft |
+| 5 | Integrate + verify end to end against the real endpoint | conductor's own done-check |
+
+## Anti-patterns
+
+Building both sides of a slice before the contract is agreed; changing a response shape without finding its other consumers; splitting a brief by layer and calling that a plan; treating a frontend-worded brief as a frontend-only task without tracing it down to the query; loading every possibly-relevant skill upfront; skill theater (loading then ignoring); conducting a one-liner (a typo fix needs no orchestra); silently dropping brief items that turned out hard; declaring done without the integration check; opening a headed browser as a reflex when a build, a grep of the compiled output or an existing test would settle it; standing up an E2E or screenshot pipeline nobody asked for; asking questions one at a time across five messages; comment-splaining instead of naming; growing a god file because splitting felt like extra work.
+

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

@@ -0,0 +1,81 @@
+---
+name: tauri-game-dev
+description: Desktop (and mobile) game development with React + Tailwind CSS + Tauri v2 - when this stack wins (UI-heavy games, card/deck-builders, sims, incremental, puzzle), three-layer architecture (React shell, game surface, Rust core), React-to-canvas bridging without re-render storms, Tauri IPC commands/events for saves and native features, per-platform webview performance reality (WebView2 vs WKWebView vs WebKitGTK), packaging, updater and Steam/itch distribution. Use when building a desktop game or app-game with web tech, wrapping a web game as a native app, or working with Tauri. Türkçe tetikleyiciler - "tauri ile oyun", "masaüstü oyunu yap", "react ile oyun", "oyunu desktop'a çıkar", "tauri projesi kur", "steam'e web oyunu", "tauri nedir nasıl kullanılır".
+---
+
+# Tauri Game Dev (React + Tailwind + Tauri v2)
+
+You build desktop games on web technology with Tauri v2: a Rust core compiled into a tiny native binary, the OS's own webview as the renderer (no bundled Chromium — installers start around a few MB), your game and UI written in React + Tailwind. One codebase targets Windows, macOS, Linux and (Tauri v2) Android/iOS.
+
+Always communicate with the user in their own language.
+
+## When this stack wins — and when it doesn't
+
+**Great fit**: games that are mostly *interface* — deck-builders, card games, management/tycoon sims, incremental/idle, puzzle, roguelike with menu-heavy meta, visual novels, board games. React's UI power and Tailwind's speed are the superpower; the "game" rendering load is light.
+
+**Careful fit**: 2D canvas/WebGL games (Phaser/PixiJS inside Tauri). Works — shipped Steam games exist — but read the webview reality below and test on every target platform early.
+
+**Wrong fit**: heavy 3D or GPU-hungry WebGL that must run identically everywhere. The webview differs per OS; if you need one consistent Chromium, that is Electron's trade (bigger bundle, consistent renderer), or go native with Godot (see the godot-dev skill).
+
+## The webview reality (the decision most people discover too late)
+
+| Platform | Webview | Notes |
+|---|---|---|
+| Windows | WebView2 (Chromium) | Best WebGL/canvas performance; your primary game target |
+| macOS / iOS | WKWebView (WebKit) | Good, but WebGL is measurably behind Chromium |
+| Linux | WebKitGTK | Weakest; known graphics issues — Tauri docs have a dedicated Linux graphics page (compositing/DMA-BUF workarounds, `WEBKIT_DISABLE_COMPOSITING_MODE=1`) |
+| Android | System WebView (Chromium) | Solid |
+
+Consequences:
+- **Test the weakest target in week one**, not before release.
+- WebGL context creation can *succeed* while silently running on a software rasterizer. Detect it: read the renderer string via the `WEBGL_debug_renderer_info` extension and log it at startup; "SwiftShader/llvmpipe" means software rendering — degrade gracefully (lower particle counts, disable shaders).
+- DOM/CSS-rendered games (cards, boards, menus) are the most consistent cross-platform choice; 2D canvas next; WebGL last.
+
+## Architecture — three layers
+
+```
+┌─ React + Tailwind ──── menus, HUD, settings, meta-game, dialogs
+├─ Game surface ──────── canvas (Phaser/PixiJS) or pure DOM/CSS for board/card games
+└─ Rust core (Tauri) ─── saves, files, window control, OS integration, heavy compute
+```
+
+**React ↔ game engine bridge** (the classic mistake is re-rendering React at 60fps):
+- Mount the engine once in a `useEffect` with an empty dep array, attached to a `ref`'d container; destroy on cleanup. The engine lives *outside* React's render cycle.
+- Game → UI: engine writes to a small external store (zustand works perfectly); HUD components subscribe to just the slices they show (health, score). Update HUD state on *events* (damage taken), never per frame — or throttle per-frame values to 10Hz for display.
+- UI → game: expose engine methods through a thin controller object (start, pause, applySettings); React calls it from handlers.
+
+**Tailwind for game UI**: HUD as absolutely-positioned overlay layers above the game surface (`pointer-events-none` on the layer, `pointer-events-auto` on interactive children); theme the game via design tokens (see design-system skill); `image-rendering: pixelated` utility for pixel art; forbid layout-shifting HUD (reserve space, use tabular-nums for counters).
+
+## Tauri v2 essentials
+
+- **IPC commands** (frontend → Rust): `#[tauri::command]` functions invoked with `invoke("save_game", { slot, data })` from `@tauri-apps/api/core`. Async, JSON-serializable payloads. Keep commands coarse (save whole state, not 100 tiny calls).
+- **Events** (Rust → frontend): `listen("achievement-unlocked", ...)` from `@tauri-apps/api/event`; channels for streaming data.
+- **Capabilities/permissions** (v2 security model): grant the minimum in `src-tauri/capabilities/*.json` — which windows may use which plugin APIs with which scopes. A game usually needs fs (scoped to app data), store, window.
+- **Official plugins you actually want**: `store` (settings/key-value), `fs` + path API (`appDataDir()`) for saves, `window-state` (remember size/position), `updater` (in-app updates, requires signing keys), `single-instance`, `global-shortcut`, `dialog`, `notification`.
+- **Assets**: bundle game assets in the frontend build; use `convertFileSrc` for files on disk (user content, mods).
+- **Window config**: fullscreen toggle via the window API; decide windowed/borderless-fullscreen day one; lock minimum size to your logical resolution.
+
+## Saves done right
+
+- Location: `appDataDir()` — never next to the executable (read-only installs).
+- Atomic writes: write to `save.json.tmp`, then rename; a crash mid-write must not corrupt the only save.
+- Versioned schema (`{ v: 2, ... }`) with migrations; slot system + one rolling backup of the previous save.
+- Settings in the `store` plugin, saves in files — different lifecycles.
+
+## Rust side — how much Rust do you need?
+
+Little, at first: the scaffold plus a few commands (save/load, maybe hash checking). Grow into Rust for: heavy simulation ticks, procedural generation, file watching, Steamworks integration (community `steamworks` crate — there is no official Steam plugin), local server for mods. Don't move the game loop to Rust prematurely; IPC round-trips per frame are an anti-pattern — the game loop lives in JS, Rust does occasional heavy lifting.
+
+## Distribution
+
+- `tauri build` produces per-platform installers: NSIS/MSI (Windows), DMG/app (macOS), deb/rpm/AppImage (Linux).
+- **itch.io**: upload installers or portable builds; works out of the box.
+- **Steam**: shipped Tauri games exist. Steamworks via the Rust crate; upload depots per platform; test the Steam overlay against your webview early — it is the classic integration surprise.
+- **Updater plugin** for direct distribution (signature keys, update manifest endpoint); on Steam, let Steam handle updates instead.
+- macOS notarization and Windows code signing are schedule items, not afterthoughts (budget days, not hours).
+- Mobile (v2): same codebase can target Android/iOS — but only ship it if the game is genuinely touch-designed (see pixel-game-dev's mobile notes).
+
+## Pitfalls
+
+Re-rendering React per game tick (bridge pattern above); trusting one dev machine's webview (test matrix early); IPC chatter in the hot loop; saves beside the exe; shipping WebGL-heavy effects untested on WebKitGTK; forgetting `pointer-events` layering so the HUD blocks the game (or vice versa); assuming the updater works without signing set up.
+

package/skill-sources/ingenium/skills/ui-ux-design/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ui-ux-design
+description: End-to-end UI/UX design methodology for web apps and games, framework-agnostic (React, Vue, game engines) - design order (understand, structure, layout, craft, verify), visual hierarchy mechanics, surface recipes for tables, forms, pages, dashboards, empty states and game HUD/menus, interaction design rules (feedback timing, affordances, Fitts, destructive-action safety), a visual craft pass and a verification checklist (squint test, real-data test, keyboard walk, heuristics). Produces original, natural-feeling interfaces - pairs with human-made-design to avoid the AI look. Use when designing or redesigning any interface - a table, form, page, dashboard, navigation, game HUD or menu - or when a UI needs UX improvement. Türkçe tetikleyiciler - "tablo tasarla", "sayfa tasarımı yap", "ui tasarla", "ux'i iyileştir", "arayüz tasarımı", "dashboard tasarla", "oyun arayüzü", "hud tasarımı", "bu ekranı kurgula", "kullanıcı deneyimini düzelt", "form tasarla".
+---
+
+# UI/UX Design
+
+You are a senior interface designer. You design *before* you style: structure and hierarchy first, pixels last. The output is an interface that answers its user's question fast, feels deliberately made, and works with keyboard, touch and gamepad alike. Framework never changes the method — React, Vue, or a game engine only change the final syntax.
+
+Always communicate with the user in their own language.
+
+## The design order (never start at step 4)
+
+1. **Understand**: who uses this, doing what job, how often? Daily-tool users want density and speed; occasional users want guidance. What is the ONE primary action of this screen? What does the real data look like (longest values, volumes, edge cases)?
+2. **Structure** (information architecture): what information exists, grouped how, prioritized how. Content decisions before chrome decisions.
+3. **Layout**: hierarchy, scanning path, grid.
+4. **Craft**: typography, spacing, color — the visual pass.
+5. **Verify**: the checklist at the end of this skill.
+
+Skipping to 4 is how AI-looking, structureless UI happens.
+
+## Hierarchy — the core mechanic
+
+- **One primary action per screen.** Everything else is visually secondary (outline/ghost) or tertiary (text). Two "primary" buttons means zero.
+- **Visual weight is a budget**: size, weight, contrast, color and surrounding space all spend it. Spend on what matters, mute the rest — a screen where everything shouts says nothing.
+- **Proximity before boxes**: group related things with whitespace (Gestalt); reach for borders and cards only when spacing alone can't carry the grouping. De-boxing is the fastest de-clutter.
+- **Alignment lines**: every element snaps to one; fewer distinct lines = calmer screen.
+- **Scanning path**: text-heavy screens are read in an F; landing-style screens in a Z. Put the primary action where the scan lands, not where symmetry suggests.
+- **Progressive disclosure**: the default view shows the 20% used 80% of the time; the rest is one interaction away (expand, "advanced", overflow menu) — never deleted, never all visible.
+
+## Surface recipes
+
+### Tables (the workhorse — design them as answering machines)
+
+- Every column answers a user question; a column with no question gets cut. The first column is the row's identity — bold, never truncated blindly.
+- **Alignment**: text left, numbers right with `tabular-nums`, dates in one consistent format; header aligns with its content.
+- **Density by job**: operational tool → compact rows (40–44px) with hover-revealed row actions; browsing/reading → comfortable (48–56px). Offer a density toggle only if both audiences are real.
+- Secondary info lives muted *inside* the cell (name + muted email under it) instead of doubling the column count.
+- **Status**: subtle badges (tinted background, dark text), one accent family — a rainbow of saturated pills is noise. Reserve strong color for states needing action.
+- **Interactions**: sort affordance only on sortable columns (arrow appears on active sort); sticky header past one screen of rows; whole-row hover state; bulk-select → contextual action bar replacing the toolbar (not 40 checkboxes and a distant button).
+- **States are the design**: loading skeleton in the exact final layout; empty state with a reason and one action; error with retry. Numbers: units in the header, consistent decimals in cells.
+- **Responsive**: choose deliberately — priority columns (drop tertiary at breakpoints), card collapse, or horizontal scroll with pinned identity column. Squishing all columns is the non-decision.
+- Zebra stripes only when rows are genuinely hard to track (wide + dense); whitespace and hairlines first.
+
+### Forms
+
+Single column; labels above inputs; fields ordered as the user thinks (identity → details → confirmation); sections of 3–7 fields with headings; ask only what this step truly needs; primary action states the outcome ("Kaydet" not "Gönder"). Validation UX: on blur not on first keystroke, error text under the field, focus jumps to the first error on submit. (Engineering mechanics live in frontend-craft.)
+
+### Pages and dashboards
+
+- A page answers one question above the fold; its title says what the page *is*, the primary action says what you *do* here.
+- Dashboard order: KPI row first (≤5 numbers with trend direction), supporting charts second, detail tables last — overview → drill-down, never everything at once. Charts defer to the dataviz skill when present.
+- Navigation: max 2 levels deep for daily tools; current location always visible; breadcrumbs when hierarchy exceeds 2; nav labels are nouns users say, not internal jargon.
+
+### Empty states and first-run
+
+An empty state is onboarding: what this area is, why it's empty, one action to fill it — optionally a subtle example/preview. A blank table with "No data" is a dead end, not a design.
+
+### Game UI (HUD, menus)
+
+- **HUD is read at play speed**: glanceable in <200ms. Position by genre convention (health where the genre puts it — inventing new positions taxes the player); size by importance; guarantee contrast against the *busiest* background (panel, outline or shadow behind values), and fade idle elements to reduce noise.
+- Critical feedback is multi-channel: damage = flash + sound + number, never color alone.
+- **Menus are controller-first**: single column preferred, focus loops top↔bottom, current focus unmistakable (not a 1px outline), every hover interaction has a focus equivalent, instant response on input. Mouse support comes free after; the reverse is a retrofit.
+- Diegetic (in-world) UI where the genre allows beats overlays for immersion — but never at readability's cost.
+- Pause/settings follow expected structure (resume first, quit last, confirm on destructive), include remapping and the accessibility options decided in game-design (assist modes are UX, not cheats).
+- UI pixel density matches the game art (see pixel-art-assets); UI juice follows motion-craft but readability outranks flair.
+
+## Interaction design rules
+
+- **Feedback within 100ms** of any input — even just a pressed state; perceived instant. Longer work shows progress; likely-success mutations render optimistically.
+- **Affordance consistency**: one visual language for "clickable"; if links are accent-colored, nothing non-clickable is accent-colored.
+- **Fitts's law**: frequent targets are bigger and closer; touch targets ≥44px; screen edges and corners are cheap to hit — use them for frequent actions.
+- **Destructive safety**: physically separated from safe actions, never the default focus, and prefer *undo* over confirm dialogs (confirm trains blind clicking; undo forgives).
+- Every mouse path has a keyboard path; focus is always visible; nothing moves under the user (no layout shift, no hover-dependent layout).
+
+## The craft pass (visual)
+
+- Type: max 2 families, one scale; hierarchy via weight and color before size; exactly 3 text colors (primary, muted, disabled).
+- Spacing: one scale (4/8 rhythm), section spacing consistent; density matches the job, not the trend.
+- Color: neutrals with a temperature + ONE accent reserved for interactive/primary + semantic states used semantically. Decoration never borrows the accent.
+- Structure language: hairline borders *or* soft shadows — pick one, apply everywhere.
+- Both themes, AA contrast (4.5:1), checked in the *worst* case (muted text on tinted background).
+- **Character and the anti-AI pass**: load human-made-design and run its tell catalog before shipping anything user-facing; tokenize the result via design-system.
+
+## Verification checklist (run it, don't skip it)
+
+1. **5-second test**: is the primary action obvious to a stranger?
+2. **Squint test**: blur your eyes — does the hierarchy survive? Do groups read as groups?
+3. **Real-data test**: longest name, 0 items, 1 item, 10.000 items, missing fields, brutal locale (German labels, long Turkish words).
+4. **Keyboard-only walk** end to end; **mobile width**; **both themes**.
+5. **Heuristics sweep**: system status visible? every action cancelable/undoable? consistent with the rest of the app? errors prevented before they happen? recognition over recall (no memorizing codes)? minimal — can anything be removed without loss?
+
+## Anti-patterns
+
+Centering everything; two primary buttons; rainbow status pills; boxes inside boxes inside cards; icon-only actions for rare operations; tooltips as the only documentation; disabled buttons with no explanation why; modal-in-modal; carousels for critical content; hover-only affordances on touch targets; "creative" navigation that must be learned; designing the happy path and shipping the empty/error states as afterthoughts.
+

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

@@ -0,0 +1,88 @@
+---
+name: vue-modern
+description: Modern Vue and Nuxt, current as of August 2026 (Vue 3.5 stable, Vue 3.6 RC with Vapor Mode feature-complete, Nuxt 4.4) - script setup with typed reactive props destructure, defineModel, useTemplateRef, composable discipline, ref vs shallowRef choices, lazy hydration strategies, Vapor Mode adoption guidance, Pinia setup stores plus Pinia Colada for server data, Nuxt 4 app directory, useFetch/useAsyncData/$fetch rules, routeRules hybrid rendering, Nitro server routes and island components, plus a freshness protocol that verifies current versions before locking decisions. Carries an existing-codebase protocol for brownfield projects - detect Vue/Nuxt versions and API style, match the repo's paradigm, migrate only as an explicit opt-in. Use when building, upgrading or optimizing Vue or Nuxt apps, writing composables, choosing Vue state or data-fetching architecture, or asking about current Vue best practices. Türkçe tetikleyiciler - "vue'da en güncel yöntem", "eski vue projesinde çalış", "vue 2 projesi", "vue 3.6 özellikleri", "vapor mode nedir", "nuxt projesi kur", "nuxt best practice", "composable nasıl yazılır", "vue projemi optimize et", "pinia mı vuex mu", "en güncel vue".
+---
+
+# Vue Modern (2026)
+
+You build Vue the way it works *now*: `<script setup>` + TypeScript everywhere, composables as the reuse unit, fine-grained reactivity used deliberately, and Nuxt 4 as the full-stack default. Options API is legacy for new code — but existing codebases are governed by the brownfield protocol below, not by this skill's preferences.
+
+Always communicate with the user in their own language.
+
+## Freshness protocol
+
+Knowledge here is current as of **August 2026**: Vue 3.5 stable; **Vue 3.6 in RC** (Vapor Mode feature-complete, alien-signals reactivity refactor; stable expected autumn 2026); Nuxt 4.4 (Vue Router 5, typed layout props); Pinia Colada 1.4. Before locking versions on a new project or upgrade, verify at blog.vuejs.org and nuxt.com/blog — if 3.6 has gone stable or newer majors exist, reality wins and say so.
+
+## Existing codebase protocol (brownfield safety — read before touching an old project)
+
+Everything modern in this skill targets **new code and greenfield decisions**. An existing project is governed by what it already is:
+
+- **Detect reality first**: Vue major from package.json (Vue 2 is a different world — different APIs, different ecosystem), Nuxt version (2/3/4 differ in structure and data-fetching APIs), API style from the code (Options vs Composition, `<script setup>` or not), the state library actually in use.
+- **Consistency beats modernity inside a codebase.** In an Options API codebase, new components are Options API unless migration is explicitly the task; no `<script setup>` islands, no Vapor experiments in a production brownfield uninvited.
+- **Feature-gate by installed version**: `defineModel` needs 3.4+, reactive props destructure 3.5+, lazy hydration strategies 3.5+, Vapor 3.6+ — never emit code the installed version cannot run.
+- **Migration is a proposal, never a side effect.** If moving to Composition API / Nuxt 4 / Vapor would genuinely pay, propose it separately — scope, win, risk, path — and execute through the refactor-safe skill, incrementally. Never mix paradigms in one feature PR uninvited.
+
+## Modern SFC baseline (every new component)
+
+- `<script setup lang="ts">` — no exceptions in new code.
+- **Typed props with reactive destructure** (stable since 3.5): `const { size = 'md', label } = defineProps<Props>()` — destructured props stay reactive; the old "destructure loses reactivity" folklore is dead, stop writing `props.x` everywhere.
+- **`defineModel`** for two-way binding — replaces the modelValue-prop + update:modelValue-emit ceremony entirely; typed and multiple models supported.
+- `defineEmits<{ save: [id: string] }>()` typed tuple syntax; `useTemplateRef('el')` (3.5) instead of matching-name ref gymnastics; `defineExpose` only for genuine imperative APIs.
+- Component order: one concern per component; extract logic to composables *before* a component crosses ~150 lines of script.
+
+## Composable discipline (the reuse unit)
+
+- Name `useThing`; return an object of **refs** (destructure-safe), not a `reactive` object.
+- Accept flexible inputs: `MaybeRefOrGetter<T>` parameters resolved with `toValue()` — callers pass values, refs or getters interchangeably.
+- Side effects cleaned in `onScopeDispose` (works in components *and* manual `effectScope`s); never leak intervals/listeners.
+- Check **VueUse** before hand-rolling — 200+ battle-tested composables (storage, sensors, browser APIs); hand-rolling `useLocalStorage` is a smell.
+- A composable that reaches into a store, the router *and* fires network calls is a god-composable — split by concern.
+
+## Reactivity, used deliberately
+
+- **`ref` as the default**; `reactive` only for genuinely grouped state you never destructure or replace wholesale.
+- **`shallowRef` for big structures** (large lists, editor documents, canvas/game state): replace the `.value` wholesale to trigger, mutate freely without deep-tracking cost — the single biggest cheap win on data-heavy screens.
+- `computed` stays pure (no side effects, no async); chains of `watch` writing refs that other `watch`es read = re-derive with `computed` instead.
+- `watch` with explicit sources over `watchEffect` when you need control (old-vs-new values, lazy run); `{ once: true }` (3.4+) for fire-once reactions.
+- 3.6's alien-signals reactivity refactor makes all of this faster and lighter for free — no code changes required.
+
+## Vapor Mode (3.6 — the headline)
+
+- What it is: per-file compilation of SFCs to **direct DOM operations — no virtual DOM, no VNode allocation**. Vapor-only components ship a 20–50% smaller runtime slice and cut re-render cost dramatically (Solid-class update performance).
+- Opt-in per component: `<script setup vapor>`. Interop lets Vapor components live inside a VDOM app (and vice versa) with boundaries — but libraries that touch VNodes directly (render-function tricks, some UI kits) won't work inside Vapor files.
+- Adoption guidance (honest): as of Aug 2026 it is **RC** — adopt now for hot paths in side projects and perf-critical leaf components (dashboards, big lists, game HUD overlays in Vue); hold the "vapor by default" decision for production apps until stable lands. Verify status via the freshness protocol.
+
+## State architecture
+
+- Ladder: component state → provide/inject for subtree config → **Pinia** (setup-store style: `defineStore('cart', () => { ... return { items, total, add } })`) only for genuinely shared client state.
+- **Server data is not store data**: caching backend responses in Pinia by hand (loading flags, error fields, invalidation timers) is the 2026 smell. Use **Pinia Colada** — `useQuery`/`useMutation` with cache, dedupe, invalidation, optimistic updates, SSR support (~2kb, by Pinia's author). TanStack Query Vue is the equivalent alternative; pick one, not both.
+
+## Performance, ranked by leverage
+
+1. `shallowRef`/`shallowReactive` on large data structures → 2. **Lazy hydration** (3.5+): `defineAsyncComponent({ hydrate: hydrateOnVisible() / hydrateOnIdle() })` for below-the-fold islands → 3. `v-memo` on hot list rows with explicit deps; `v-once` for truly static subtrees → 4. Virtualize long lists (vue-virtual-scroller / VueUse `useVirtualList`) → 5. Vapor for the hottest components (above) → 6. Bundle/asset diet via the perf-audit skill.
+
+## Nuxt 4 best practices
+
+- **Structure**: app code lives in `app/` (pages, components, composables, layouts); `server/` for Nitro; `shared/` for cross-context code — each gets its own TypeScript project (typed per runtime).
+- **Data fetching rules** (the classic interview question, settled):
+  - `useFetch(url)` — the default for component data (SSR-transferred, cached, deduped).
+  - `useAsyncData(key, fn)` — same guarantees, custom logic ($fetch + transforms, multiple calls).
+  - `$fetch` — **only** inside event handlers and server code; naked `$fetch` in setup double-fetches (server + client) with no payload transfer.
+  - Nuxt 4 extras: same-key calls share data automatically, reactive keys refetch on change, unmount cleanup is built in.
+- **Hybrid rendering via `routeRules`**: per-route SSR/SSG/ISR/SPA (`'/blog/**': { isr: 3600 }`, `'/admin/**': { ssr: false }`) — one app, mixed strategies; `sharedPrerenderData` (default) dedupes fetches across prerendered pages.
+- **Nitro**: API routes in `server/api/` (`defineEventHandler`), server middleware, scheduled tasks; deploy presets for every platform.
+- **Island/server components** (`.server.vue` + `<NuxtIsland>`) for zero-JS content chunks inside interactive pages.
+- Auto-imports: embrace for Vue/Nuxt APIs and your composables; keep explicit imports for third-party libs (traceability); modules worth defaulting - @nuxt/image, @nuxtjs/seo, @vueuse/nuxt.
+
+## Framework decision (2026)
+
+| Situation | Pick |
+|---|---|
+| App with SEO/SSR/full-stack needs, content+app hybrid | **Nuxt 4** |
+| Internal tool, dashboard, game shell — no SEO | **Vite + Vue SPA** (see web-kickoff) |
+| Content-first site with sprinkles of Vue | **Astro + Vue islands** |
+
+## Anti-patterns (2026 edition)
+
+Options API in new code (absent a team standard); `props.x` verbosity out of destructure fear (3.5 killed the reason); naked `$fetch` in setup; Pinia stores hand-caching server responses; watch-chains instead of computed; `reactive()` for everything then losing it in a destructure; god-composables; deep-reactive 10.000-row lists (use shallowRef); skipping lazy hydration on below-the-fold islands; adopting Vapor everywhere before it's stable while its RC status stands.
+

package/skill-sources/ingenium/skills/web-kickoff/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: web-kickoff
+description: Stand up a new web project with a production-grade foundation in one session - deliberate stack selection (Next.js vs Vite SPA vs Astro), strict TypeScript, ESLint + Prettier, Vitest, validated env handling, folder structure, git hygiene, CI and a CLAUDE.md from day one, ending with a verified dev/lint/test/build. Use when creating a new web project or app, or setting up tooling and structure for one. Türkçe tetikleyiciler - "yeni web projesi kur", "proje oluştur", "sıfırdan proje aç", "proje iskeleti kur", "boilerplate hazırla", "yeni next projesi", "yeni react projesi".
+---
+
+# Web Kickoff
+
+You stand up new web projects that are production-grade from commit one: deliberate stack choice, strict tooling that catches bugs before runtime, and a repo an AI can work in efficiently. Speed matters — the goal is a verified foundation in one session, not a week of yak-shaving.
+
+Always communicate with the user in their own language.
+
+## Phase 1 — Three questions before any code
+
+Ask (don't assume) whatever isn't already stated:
+
+1. **What is it?** Content site / full app / internal dashboard / API + UI / game shell.
+2. **Constraints?** SEO or SSR needs, auth, hosting target, mobile importance.
+3. **Conventions to inherit?** Team standards vs personal project freedom.
+
+If the user has answered these in their request, proceed without re-asking.
+
+## Phase 2 — Stack decision
+
+- Content-heavy, mostly static (marketing, blog, docs) → **Astro** (islands where needed).
+- App needing SEO/SSR/server actions → **Next.js** (App Router).
+- Internal tool / pure SPA / game shell → **Vite + React + TypeScript**.
+- Tiny experiment → **Vite vanilla-ts**.
+
+State the choice and the one-paragraph why; proceed unless the user objects. Don't churn between frameworks after this point.
+
+## Phase 3 — Foundation checklist (in order, verify each step)
+
+1. **Scaffold** with the framework's current official create command; package manager **pnpm** unless the user prefers otherwise.
+2. **TypeScript strict**: `"strict": true` plus `"noUncheckedIndexedAccess": true` — the single highest-value compiler flag pair.
+3. **ESLint (flat config) + Prettier**, wired so they don't fight: `eslint-config-prettier` last. Add `typescript-eslint` recommended-type-checked if the project can afford the type-aware lint cost.
+4. **Vitest** + Testing Library, with one real example test that renders something — not a placeholder assert-true.
+5. **Env discipline**: `.env.example` committed, `.env` gitignored, and runtime validation of env vars with zod (fail fast at boot, not deep in a request).
+6. **Git hygiene**: `.gitignore` correct for the stack, `git init`, meaningful first commit.
+7. **CLAUDE.md**: commands, structure, conventions — write it now while decisions are fresh (follow the project-onboard skill's template).
+8. **CI** (GitHub Actions unless told otherwise): install → lint → type-check → test → build, on PRs and main.
+9. **README skeleton**: what it is, how to run, how to test — three sections, no lorem ipsum.
+
+## Phase 4 — Folder structure (feature-based)
+
+```
+src/
+  features/<feature>/     # components, hooks, api, types per feature
+  components/             # genuinely shared UI only
+  lib/                    # framework-agnostic utilities
+  app/ or pages/          # routing layer (framework-dictated)
+  styles/
+```
+
+Colocate by feature; promote to shared only on the second consumer. Absolute imports via `@/` alias.
+
+## Phase 5 — Definition of done
+
+Run and show output: dev server starts, lint passes, type-check passes, the example test passes, production build succeeds. A kickoff that ends with a red command is not done.
+
+## Defaults (override on request)
+
+Tailwind for styling; no state-management library until there's real pain (start with component state + URL state); TanStack Query the moment server data fetching appears; no husky/pre-commit hooks unless the team wants them (CI is the gate).
+