@appaflytech/zeyrek-ai-mcp 0.0.10 → 0.0.12

package/dist/knowledge/themeResolve.js

@@ -252,7 +252,9 @@ const BASE_TOKENS = {
 };
 export const TOKENS = BASE_TOKENS;
 /** Palet gruplarının anahtarları — paletin KENDİSİNDEN türer ki listeyi ikinci kez yazmayalım. */
-export const PALETTE_GROUPS = Object.fromEntries(Object.entries(WHITE_PALETTE).map(([group, values]) => [group, Object.keys(values)]));
+/** Tabanda BULUNMAYAN, yalnız override olarak yazılabilen anahtarlar (f-08: `accent.onPrimary` → `--ng-text-on-accent`). */
+export const OPTIONAL_PALETTE_KEYS = { accent: ['onPrimary'] };
+export const PALETTE_GROUPS = Object.fromEntries(Object.entries(WHITE_PALETTE).map(([group, values]) => [group, [...Object.keys(values), ...(OPTIONAL_PALETTE_KEYS[group] ?? [])]]));
 /* ---- Birleştiriciler ve ölçekler (`utils.ts` kopyası) ---- */
 export function mergePalette(base, overrides) {
     const result = { ...base };
@@ -685,7 +687,7 @@ export function buildThemeStyle(palette, form, t, shadow, formDefaultSize) {
 	--ng-action-yellow: ${actions.yellow || colors.yellow.r600};
 	--ng-action-white: ${actions.white || palette.background.surface};
 	--ng-action-black: ${actions.black || colors.grey.r900};
-	--ng-text-on-accent: ${getContrastColor(palette.accent.primary)};
+	--ng-text-on-accent: ${palette.accent.onPrimary || getContrastColor(palette.accent.primary)};
 `;
 }
 /** Temanın yaydığı değişken adlarının tam listesi — elle tutulmaz, gerçek şablondan türer. */

package/dist/platform/errors.js

@@ -177,6 +177,79 @@ function diagnoseKnownFailure(status, message, code, context) {
     }
     return '';
 }
+const MaxErrorCauseWalk = 32;
+const MaxErrorPathShown = 6;
+const MaxErrorTextLength = 400;
+function nonEmptyText(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return undefined;
+    return value.length > MaxErrorTextLength ? `${value.slice(0, MaxErrorTextLength)}…` : value;
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function errorLevels(body) {
+    const levels = [];
+    let current = asRecord(body);
+    while (current) {
+        if (levels.length === MaxErrorCauseWalk)
+            return { levels, truncated: true };
+        const step = asRecord(current.step);
+        const name = nonEmptyText(step?.name);
+        const stepType = nonEmptyText(step?.type);
+        levels.push({
+            step: name ? `'${name}'${stepType ? ` (${stepType})` : ''}` : undefined,
+            code: nonEmptyText(current.code),
+            message: nonEmptyText(current.message),
+            detail: nonEmptyText(current.detail),
+            type: nonEmptyText(current.type)
+        });
+        current = asRecord(current.cause);
+    }
+    return { levels, truncated: false };
+}
+function seenKey(...parts) {
+    return JSON.stringify(parts);
+}
+/**
+ * Workflow 5xx gövdesinden, başlıkta zaten yazılmış `code`/`message` dışında kalan bilgiyi çıkarır.
+ * İki gövde şekli okunur: platformun `WorkflowStepErrorResponse`'u `{ code, message, detail, type }`
+ * (hata yolu olmayan akış, `ExceptionHandler.cs`) ve gateway hata adımının gövdesi
+ * `{ …, step: { name, type }, cause }` (`errorPath.ts`). `cause` zinciri alt akış seviyelerini
+ * taşır; aynı kod+mesaj her seviyede tekrarlandığı için mesaj EN DERİNDEN başlanarak bir kez, hatanın
+ * doğduğu adıma atfedilerek yazılır. Kodla aynı `type` ve mesajla aynı `detail` gürültüdür. Uzun
+ * zincirde yolun başı ve SONU gösterilir (hatanın doğduğu adım kaybolmasın); metinler kırpılır.
+ */
+export function describeErrorBody(body, shown) {
+    const { levels, truncated } = errorLevels(body);
+    const fragments = [];
+    const path = levels.map(level => level.step).filter((step) => step !== undefined);
+    const shownPath = path.length > MaxErrorPathShown ? [...path.slice(0, 2), '…', ...path.slice(-3)] : path;
+    if (shownPath.length > 0)
+        fragments.push(`hata yolu: ${shownPath.join(' → ')}${truncated ? ' → …' : ''}`);
+    const seen = new Set();
+    if (shown) {
+        seen.add(seenKey('head', shown.code, shown.message));
+        if (levels[0])
+            seen.add(seenKey('head', levels[0].code, levels[0].message));
+    }
+    for (const level of [...levels].reverse()) {
+        const key = seenKey('head', level.code, level.message);
+        if ((level.code || level.message) && !seen.has(key)) {
+            seen.add(key);
+            fragments.push(`${level.step ? `${level.step} ` : ''}${[level.code, level.message].filter(Boolean).join(': ')}`);
+        }
+        if (level.detail && level.detail !== level.message && !seen.has(seenKey('detail', level.detail))) {
+            seen.add(seenKey('detail', level.detail));
+            fragments.push(`detail: ${level.detail}`);
+        }
+        if (level.type && level.type !== level.code && !seen.has(seenKey('type', level.type))) {
+            seen.add(seenKey('type', level.type));
+            fragments.push(`type: ${level.type}`);
+        }
+    }
+    return fragments;
+}
 export function mapPlatformError(status, payload, context) {
     const body = payload && typeof payload === 'object' ? payload : {};
     const code = typeof body.code === 'string' ? body.code : undefined;
@@ -222,7 +295,9 @@ export function mapPlatformError(status, payload, context) {
     }
     const fallbackValidationMessages = collectValidationMessages(body);
     const fallbackDetail = fallbackValidationMessages.length > 0 ? ` → ${fallbackValidationMessages.join(' ; ')}` : '';
-    return new PlatformApiError(`Platform hatası ${status} (${location}): ${apiMessage ?? 'beklenmeyen hata'}${code ? ` [${code}]` : ''}${fallbackDetail}${diagnoseKnownFailure(status, apiMessage ?? '', code, context)}`, status, code);
+    const errorBody = status >= 500 ? describeErrorBody(body, { code, message: apiMessage }) : [];
+    const errorBodyDetail = errorBody.length > 0 ? ` — ${errorBody.join(' · ')}` : '';
+    return new PlatformApiError(`Platform hatası ${status} (${location}): ${apiMessage ?? 'beklenmeyen hata'}${code ? ` [${code}]` : ''}${errorBodyDetail}${fallbackDetail}${diagnoseKnownFailure(status, apiMessage ?? '', code, context)}`, status, code);
 }
 export function mapNetworkError(error, context) {
     const cause = error instanceof Error ? error : new Error(String(error));

package/dist/platform/responses.js

@@ -1,5 +1,5 @@
 import { logError, logStep } from '../observability/trace.js';
-import { PlatformApiError } from './errors.js';
+import { PlatformApiError, describeErrorBody } from './errors.js';
 import { PolicyBlockError } from '../knowledge/policy.js';
 import { maskSecrets } from './secrets.js';
 export function prune(value) {
@@ -76,6 +76,17 @@ export function runtimeErrorSummary(payload) {
     const errors = [];
     if (typeof record.httpStatus === 'number' && record.httpStatus >= 400) {
         errors.push(`httpStatus: ${record.httpStatus} — çağrı ${record.httpStatus} ile bitti; gövde başarı çıktısı değil hata gövdesidir. Adım adım bakmak için microservice_debug kullanın.`);
+        // Yalnız 5xx: 4xx gövdeleri (422 doğrulama, 401) bilinçli iş yanıtıdır ve zaten gövdede okunur.
+        // `/debug/` ucu gövdeyi her zaman, `/m/` ve servis önizlemesi ise uiActions kurulmuşsa
+        // `{ data, uiActions[, executionItems] }` ile sarar (MicroservicesController.Debug / HandleResult).
+        const raw = record.body && typeof record.body === 'object' && !Array.isArray(record.body) ? record.body : undefined;
+        const wrapped = raw !== undefined && ('executionItems' in raw || 'uiActions' in raw) && raw.data && typeof raw.data === 'object' && !Array.isArray(raw.data);
+        const errorBody = wrapped ? raw.data : raw;
+        const describable = record.httpStatus >= 500 && errorBody !== undefined &&
+            (typeof errorBody.code === 'string' || Boolean(errorBody.step && typeof errorBody.step === 'object') || Boolean(errorBody.cause && typeof errorBody.cause === 'object'));
+        const fragments = describable ? describeErrorBody(errorBody) : [];
+        if (fragments.length > 0)
+            errors.push(`hata gövdesi — ${fragments.join(' · ')}`);
     }
     const stepErrors = [];
     collectStepErrors(body.steps, stepErrors);

package/dist/resources/examples/design-snapshot.json

@@ -0,0 +1,157 @@
+{
+  "_meta": {
+    "synthetic": false,
+    "note": "Figma dosyasından 2026-09-16 tek geçiş protokolüyle okunan gerçek anlık görüntü: 8 çağrı (get_metadata sayfa listesi · get_variable_defs iki frame · get_metadata Deals frame ağacı · get_screenshot Deals · get_design_context buton ve durum rozeti, excludeScreenshot) ≈ 29 bin karakter. Kit iki token dili taşır (Fonts/*, Light/Basic/*); hints ajanın kararıdır ve dosyada kalır — ikinci oturum Figma'ya dönmez. Gölge (effects) okunmadı, alan yok.",
+    "usage": "Gövde <themeDiscoverArgs.snapshot> theme_discover'a verilir; öneri theme_update({ theme, dryRun: true }) ile önizlenir, sonra yazılır. Dosyanın yeri: zeyrek-mcp/docs/<koşu>/design/<fileKey>.snapshot.json."
+  },
+  "_rules": [
+    "Bütçe: tasarım dosyası başına ≤ 8 Figma çağrısı, bağlama giren ≤ 150 bin karakter; get_design_context yalnız atomik bileşene (excludeScreenshot: true), ekran frame'ine asla.",
+    "variables get_variable_defs çıktısının kendisidir — ad yeniden yazılmaz, değer olduğu gibi taşınır (Font(...) değerleri metin stili olarak okunur); eşleme adı okur.",
+    "Eşlenmeyen token için Figma'ya dönülmez: karar hints'e yazılır (tema yolu ya da ignore). Sayfa düzeyinde get_variable_defs seçim ister — frame id verin.",
+    "Koyu palet aydınlıktan türetilmez: variablesDark yoksa paletteDark boşluk kalır (THEME-009); isteğe bağlı deriveDark: true başlangıç noktası üretir."
+  ],
+  "themeDiscoverArgs": {
+    "snapshot": {
+      "source": {
+        "kind": "figma",
+        "fileKey": "9NnUskJSeNkMy1gAU2fAaA",
+        "fileName": "Recurring | Saas Company Management System (Community) (Copy)",
+        "nodeIds": [
+          "0:1",
+          "92:4339",
+          "79:8715",
+          "92:4343",
+          "92:5596"
+        ],
+        "fetchedAt": "2026-09-16",
+        "calls": 8,
+        "characters": 29000
+      },
+      "variables": {
+        "Primary": "#4787FA",
+        "Fonts/Primary": "#25213B",
+        "Fonts/Primary Variant": "#6E6893",
+        "Fonts/Primary Icon": "#8B83BA",
+        "Fonts/Positive": "#007F00",
+        "Backgrounds/Stripe": "#F4F2FF",
+        "White Primary": "#F3F4F8",
+        "Table/Footer": "Font(family: \"Inter\", style: Semi Bold, size: 12, weight: 600, lineHeight: 100, letterSpacing: 5)",
+        "Light/Basic/Primary": "#242731",
+        "Light/Basic/Secondary": "#575F6E",
+        "Light/Basic/Thriary": "#79808F",
+        "Light/Basic/Strokes": "#D4D4D4",
+        "Light/Basic/White": "#FFFFFF",
+        "Light/Accent/Primary": "#4277FF",
+        "Light/Background/Secondary": "#E3EBFF",
+        "Light/Background/Contrast": "#242731",
+        "Light/Invertion/Primary": "#FFFFFF"
+      },
+      "textStyles": [
+        {
+          "name": "Button label",
+          "fontFamily": "DM Sans",
+          "fontSize": 14,
+          "fontWeight": 700
+        },
+        {
+          "name": "Status pill",
+          "fontFamily": "Inter",
+          "fontSize": 12,
+          "fontWeight": 500
+        }
+      ],
+      "layout": {
+        "desktopWidth": 1440,
+        "mobileWidth": 375,
+        "sidebarWidth": 94,
+        "notes": [
+          "Kabuk (get_metadata 92:4339): solda 94 px 'Admin Nav' rayı, üstte 76 px 'Admin Top Nav'; içerik x=94'ten başlar, 1345 px genişlik",
+          "Liste (Deals): 'Headers' şeridi 76 px — solda 39 px yüksekliğinde başlık metni, sağda hap biçimli 202×46 px birincil buton; altında 48 px sekme şeridi (All · Paid · Unpaid · Overdue, aktif sekmenin altında 2 px çizgi) ve sağda toplam tutar; 45 px tablo başlığı (büyük harf); 61 px satırlar; satırda durum pill'i (19 px, önünde 6 px nokta), 'View More' ikincil buton 71×25, satır sonu 'Shape/More'; altta 53 px Pagination",
+          "Form (Create Client Modal 79:8715) iki token dili taşıyor: 'Light/Basic/*' metin tonları, 'Light/Accent/Primary' #4277FF (Deals'in #4787FA'sından farklı ikinci bir accent) — kit iki tasarım sisteminin karışımı",
+          "Masaüstü ızgarası iki nesil: eski ekranlar 1440×1024, yeni İK ekranları 1728×1117 — 1440 taban alındı"
+        ]
+      },
+      "components": {
+        "button/primary": {
+          "background": "#4787FA",
+          "color": "#FFFFFF",
+          "borderRadius": 23,
+          "height": 46,
+          "paddingX": 29,
+          "paddingY": 14,
+          "fontSize": 14,
+          "fontWeight": 700
+        },
+        "badge/status": {
+          "background": "#E6E6F2",
+          "color": "#4A4AFF",
+          "borderRadius": 10,
+          "height": 19,
+          "paddingX": 18,
+          "paddingY": 2,
+          "fontSize": 12,
+          "fontWeight": 500
+        }
+      },
+      "screens": [
+        {
+          "nodeId": "92:4339",
+          "name": "Deals",
+          "role": "list",
+          "notes": [
+            "sekme filtreleri + toplam tutar vurgusu + pill rozetler; 11 satır + Pagination"
+          ]
+        },
+        {
+          "nodeId": "74:4098",
+          "name": "Clients",
+          "role": "list"
+        },
+        {
+          "nodeId": "79:8715",
+          "name": "Create Client Modal",
+          "role": "form"
+        },
+        {
+          "nodeId": "310:5445",
+          "name": "grant leave",
+          "role": "form"
+        },
+        {
+          "nodeId": "310:3809",
+          "name": "employee profile",
+          "role": "detail"
+        },
+        {
+          "nodeId": "230:3757",
+          "name": "Login",
+          "role": "auth",
+          "notes": [
+            "767 px mobil varyantı var"
+          ]
+        },
+        {
+          "nodeId": "8:3389",
+          "name": "settings",
+          "role": "other"
+        }
+      ],
+      "hints": {
+        "Light/Accent/Primary": "ignore",
+        "Light/Basic/Primary": "ignore",
+        "Light/Basic/Secondary": "ignore",
+        "Fonts/Primary Variant": "text.secondary",
+        "Fonts/Primary Icon": "ignore",
+        "Fonts/Positive": "status.success",
+        "Backgrounds/Stripe": "background.surfaceAlt",
+        "White Primary": "background.canvas",
+        "Light/Basic/Thriary": "text.disabled",
+        "Light/Basic/Strokes": "border.primary",
+        "Light/Basic/White": "background.surface",
+        "Light/Background/Secondary": "accent.subtle",
+        "Light/Background/Contrast": "background.inverse",
+        "Light/Invertion/Primary": "accent.onPrimary"
+      }
+    }
+  }
+}

package/dist/resources/guides/theme.md

@@ -18,7 +18,7 @@ yazmalarının aksine burada "önce development'ta dene" diye bir ayrım YOKTUR.
 | Alan | Ne yapar | Ürettiği değişken(ler) |
 |---|---|---|
 | `mode` | `'light'` (varsayılan) \| `'dark'` — yayınlanan uygulamanın modu | palet tabanını seçer |
-| `palette` | AYDINLIK moddaki renk override'ları | `--ng-accent-*` · `--ng-background-*` · `--ng-text-*` · `--ng-border-*` · `--ng-status-*` |
+| `palette` | AYDINLIK moddaki renk override'ları; `accent.onPrimary` isteğe bağlıdır — accent ÜSTÜNDEKİ metin, verilmezse kontrasttan türer (`#4787FA` gibi açık bir mavi siyah metin üretir, tasarımda beyazsa buraya yazın) | `--ng-accent-*` · `--ng-background-*` · `--ng-text-*` · `--ng-border-*` · `--ng-status-*` · `--ng-text-on-accent` |
 | `paletteDark` | KARANLIK moddaki renk override'ları | aynı küme |
 | `fontFamily` · `headingFontFamily` | Gövde ve başlık yazı tipi (Google Fonts adı) | `--ng-font` · `--ng-font-heading` |
 | `fontSize` · `fontWeight` | Taban punto ve ağırlık | `--ng-font-size` · `--ng-font-weight` |
@@ -208,3 +208,86 @@ kareyi de alın: `page_screenshot(…)` ve `page_screenshot(…, colorScheme: 'd
 **Renkler hex olmalı.** CSS `rebeccapurple`'ı çizer ama studio'nun renk alanları hex bekler
 ve vurgu üstündeki metin rengi (`--ng-text-on-accent`) accent'i karakter karakter okuyup
 kontrast hesapladığı için tanımadığı değerde beyaza düşer (THEME-005).
+
+## Tasarım dosyasından tema (Figma) — tek geçiş
+
+Bir Figma dosyası **bir kez** okunur, makine-okur bir **anlık görüntüye** alınır ve tema o
+dosyadan türetilir. Sonrası Figma'sızdır: sayfa kurma, preset bağlama ve koyu mod anlık görüntü +
+`theme_get` ile yürür. Ölçüm (2026-09-16): ekran frame'lerine atılan altı `get_design_context`
+çağrısı yaklaşık **bir milyon karakter** React kodu getirdi; kullanılan yalnız renk, boşluk, yazı
+tipi ve düzendi. O bilgi Figma'nın ucuz tool'larından çıkar.
+
+**Bütçe: tasarım dosyası başına ≤ 8 Figma çağrısı, bağlama giren ≤ 150 bin karakter.**
+İş tanımına frame URL'lerini yazdırın — sayfa düzeyinde ağaç dökümü tek başına 1 MB'tır.
+
+| Adım | Figma çağrısı | Bütçe | Anlık görüntüye ne girer |
+|---|---|---|---|
+| 1 | `get_metadata(fileKey)` — `nodeId` YOK | 1 çağrı, < 2 K | `source.fileName`, sayfa id'si |
+| 2 | **Koşullu:** insan frame URL'si vermediyse `get_metadata(fileKey, nodeId: <sayfa>)`; yalnız üst seviye frame'lerin ad + id'si okunur | 1 çağrı; büyükse harness dosyaya alır | `screens[]` (`role`'ü siz atarsınız: shell · list · form · detail · auth · other) |
+| 3 | `get_variable_defs(fileKey, nodeId: <kütüphane/Components frame'i, yoksa ana ekran>)`; koyu mod frame'i varsa ona da. **Sayfa id'si (`0:1`) çalışmaz** — "select a layer" hatası; her zaman frame id verin. Farklı frame'ler farklı token dili taşıyabilir (ölçüldü: `Fonts/*` ve `Light/Basic/*` aynı dosyada) — iki temsilci frame yeter | 1–2 çağrı, 0,5–10 K | `variables`, `variablesDark` — **olduğu gibi**, ad yeniden yazılmaz; `Font(family: …, size: …, weight: …)` değerleri metin stili olarak okunur |
+| 4 | `get_screenshot(fileKey, nodeId, maxDimension: 800)` — liste, form, detay için birer | ≤ 3 çağrı; varsayılan URL kipi, `curl -o` ile diske | `screens[].screenshot` (yerel yol), `layout.notes` (gözlem: ray genişliği, ızgara, kart/pill dili) |
+| 5 | `get_design_context(fileKey, nodeId: <ATOMİK bileşen>, excludeScreenshot: true)` — button, badge, input; **ekran frame'ine ASLA** | ≤ 2 çağrı | `components` (ölçüler), `textStyles`, `effects` |
+
+Tip ölçeği için sıra: (a) `variables` içinde `font/size/h1` gibi adlar, (b) kütüphanede bir
+"Typography" bileşeni varsa 5. adımın bir çağrısı ona, (c) yoksa alan boş kalır ve tema önerisi
+bunu `gaps` ile söyler — ekran frame'i bunun için de açılmaz.
+
+**Anlık görüntü sözleşmesi** (`design-snapshot` altın örneği; her seviyede strict, tanınmayan
+anahtar reddedilir):
+
+| Alan | Ne |
+|---|---|
+| `source` | `kind` (`figma` \| `manual`), `fileKey`, `fileName`, `nodeIds`, `fetchedAt`, ölçüm için `calls` ve `characters` |
+| `variables` · `variablesDark` | `get_variable_defs` çıktısı: `{ 'Primary': '#4787FA', 'spacing/md': 16 }`; koyu küme ayrı |
+| `textStyles[]` | `name`, isteğe bağlı `role` (h1…small), `fontFamily`, `fontSize` (px), `fontWeight`, `lineHeight` |
+| `effects[]` | gölge: `name`, offset/blur/spread, `color`, `opacity` (Figma'nın 0–1'i) |
+| `layout` | `desktopWidth`, `mobileWidth`, `gutter`, `sidebarWidth`, `notes[]` — temaya gitmez, sayfa fazı için saklanır |
+| `components` | `'button/primary'` → `background`, `color`, `border`, `borderRadius`, `paddingX/Y`, `height`, `fontSize`, `fontWeight`, `shadow` |
+| `screens[]` | `nodeId`, `name`, `role`, `screenshot` (yerel yol), `notes[]` |
+| `hints` | Figma adı → tema yolu (`accent.muted`, `colors.blue.500`) ya da `ignore` — **sizin kararınız, kalıcı** |
+
+Dosya koşu klasöründe yaşar: `zeyrek-mcp/docs/<koşu>/design/<fileKey>.snapshot.json`. Ekran
+görüntüleri repoya girmez. Gateway bu dosyayı hatırlamaz (HTTP taşımasında her çağrı yeni
+sunucudur); ikinci oturum dosyayı okur, Figma'ya dönmez.
+
+**Eksik değer için Figma'ya dönülmez.** Öneri bir token'ı eşleyemediyse sebebini `unmapped`'da
+söyler; kararı `hints`'e yazıp yeniden çevirirsiniz. Değer dosyada hiç yoksa (`gaps`) ekran
+görüntüsünden ya da insandan alıp anlık görüntüye elle eklersiniz (`source.kind` `figma` kalır,
+`notes` söyler). Koyu palet aydınlıktan türetilmez: `variablesDark` yoksa `paletteDark` boşluktur
+(THEME-009 uyarır).
+
+Akış: anlık görüntüyü yaz → `theme_discover({ snapshot })` → `unmapped`/`gaps`'e bak, `hints` yaz →
+`theme_discover` yeniden (`project` verirseniz mevcut temaya göre `cssVarsChanged` önizlemesi de
+gelir) → `theme_update({ theme, dryRun: true })` → `theme_update({ theme })` →
+`theme_get(view:'resolved')` → `page_screenshot` (aydınlık + `colorScheme:'dark'`). Bu rehberin
+§Doğrulama sırası aynen geçerlidir.
+
+`theme_discover` yazmaz ve tahmin etmez: öneri `theme_update` şemasındadır, `mapping` her Figma
+adının hangi yola hangi kuralla (`role` · `ramp` · `hint` · `textStyle` · `variable` · `effect` ·
+`component` · `component→var`) gittiğini söyler; yalnız SAPAN değer yazılır (platform varsayılanına
+eşit taban ve ±0,05 içindeki oran öneriye girmez). Tek istisna `typeScale.p: 1` — platformda p
+tabanın 0,925'idir, Figma gövdesi tabanın kendisi olduğu için yazılmazsa 15 px gövde 13,9 px
+çizilir. Grup kelimesinin yanında tanınmayan bir niteleyici (`bg/error`, `text/on-primary`,
+`button/primary`) varsayılana DÜŞMEZ, `unmapped` olur — kararı `hints` ile verirsiniz. Bileşen
+ölçüleri adlı preset olur ve eşlenmiş renkler `var(--ng-*)` ile bağlanır (preset temayı izler);
+`componentPresets` üretilmez. Gateway'in düzelttiği değerler (hex büyük harf, `rgba` → hex, gölge
+`opacity` ×100, yazı tipi yazımı) yanıtta `gatewayNormalized` ile listelenir.
+
+Bileşen adının ilk kelimesi katalogdaki bir TİP ise (`button/primary` → `button`) aynı ölçüler o
+tipin **bileşen preseti** (`componentPresets.button.versions.V1.props.style`) olarak da önerilir:
+adlı preset mevcut düğümlere bağlanır, bileşen preseti yeni düğümlere başlangıç olur. `input` katalog
+tipi değildir ve `textinput` diye düzeltilmez — adı katalog tipiyle başlatın (`component_list`).
+Koyu palet varsayılan olarak türetilmez; `theme_discover({ snapshot, deriveDark: true })` Figma'da
+koyu küme YOKSA accent/status değerlerinden deterministik bir başlangıç noktası üretir ve her değeri
+`via: 'derived'` ile işaretler — marka kararı değil, koyu kareyi görüp düzeltmek sizin işiniz.
+
+**Ekranlar için `page_discover`.** Anlık görüntüdeki bir ekranın rolünden (list · form · detail ·
+auth · shell) altın örnek arketipini seçip `page_create` + `page_schema_patch` iskeletini döner;
+`theme_discover`'ın ürettiği adlı preset tek adaysa bileşene `props.style.$preset` olarak bağlanır.
+Piksel kopyası değildir: `caveats` neyin doldurulacağını, `next` çağrı sırasını söyler.
+
+`hints` biçimleri: çıplak `accent.hover` **iki kümeye de** uygulanır (Figma modları aynı adı
+aydınlık ve koyu değerle verir — `variables`'taki `palette`'e, `variablesDark`'taki
+`paletteDark`'a gider); `palette.accent.hover` / `paletteDark.accent.hover` yalnız kendi kümesinde;
+`colors.blue.500` rampaya (yalnız aydınlık); `ignore` hiç eşleme. Anlık görüntüde olmayan bir ada
+hint yazmak hatadır — Figma'da ad değiştiyse hint de değişir.

package/dist/resources/guides/workflow.md

@@ -227,19 +227,68 @@ tanımı kendi global-error dalınla gönder — dal **bağlıysa** (`nextStepId
 dokunmaz. `nextStepId: null` ile bağlanmamış gönderirsen gateway ikinci bir dal eklemez, mevcut
 dalını enjekte ettiği hata adımına bağlar.
 
-**Fail dallarını tek tek bağlamana gerek yok.** Bir adımın `fail` dalı bağlanmamışsa
-(`nextStepId: null`) ya da hiç yoksa, hata **kendiliğinden** global-error dalına gider. `fail`
-dalını yalnız o adıma özel bir telafi akışı (örn. "kayıt yoksa oluştur") istiyorsan bağla.
+### `gatewayOnError`'un 500 gövdesi: patlayan adım ve alt akış zinciri (2026-09-16)
+
+```jsonc
+// POST /m/web/ticket-ac → 500   (ebeveyn → callChild → çocuk akış → childBoom patladı)
+{ "code": "JavaScriptException", "message": "Error: x is not defined\n   at <anonymous>:1:8",
+  "detail": "…", "type": "JavaScriptException",
+  "step":  { "name": "callChild", "type": "workflow" },          // bu akışta patlayan adım
+  "cause": { "code": "JavaScriptException", "message": "…",       // alt akışın KENDİ hata gövdesi
+             "step": { "name": "childBoom", "type": "code" } } }   // çocukta patlayan adım
+```
+
+- **`step` yalnız `{ name, type }`'tır.** `error.step.input` ifade değerlerini (parola dahil),
+  `error.step.data` adımın çıktısını taşır; ikisi de dışarı yazılmaz. `error.step`'i bütün olarak
+  gövdeye koyarsan platform onu **siler** (`ResponseStep` global-error kipinde `error.step` ile
+  birebir aynı `step` alanını kaldırır) — alt küme yaz.
+- **`cause` bir seviye aşağıyı taşır** ve her seviyede yalnız `code`, `message`, `detail`, `type`,
+  `step { name, type }` ve `cause` geçer (gateway beyaz listeye süzer, en fazla dokuz seviye). Backend
+  2026-09-17'den beri zinciri `error.cause`'ta kendisi kurar; üç durum kapsanır:
+  - **Alt akış patladı:** `cause.step` çocukta patlayan adım, çocuk da alt akış çağırıyorsa zincir
+    seviye seviye iç içe iner. Çocuk Studio'da hata yolsuz kurulduysa da adım adı gelir.
+  - **Loop iterasyonu patladı:** `step` loop adımı, `cause.step.name` `loopRows[0]` gibi
+    `<loop adı>[<sıra>]`, iterasyondaki alt akışın zinciri onun altında.
+  - **Çocuk istisnasız 2xx dışı döndü** (`response` 422): `code` `SubWorkflowFailedException`,
+    `message` `Sub-workflow '<ad>' returned 422 (<gövde code>): <gövde message>`.
+
+  Eski backend'de `error.cause` yoktur; gateway o zaman patlayan `workflow` adımının `step.data`'sına
+  (çocuğun kendi gövdesi) düşer — loop ve istisnasız çocuk orada kaybolur. Çocuk kendi 4xx/5xx yanıtını
+  elle yazdıysa (`({ success: false, token })`, `({ err: error })`) o gövdenin yalnız bu alanları geçer.
+  Canlı ölçüldü (2026-09-16/17): torunun `token` ve `step.input`'u üst gövdeye ulaşmadı; üç seviyeli
+  zincir ve `loopRows` → `loopRows[0]` → `boomStep` hem hata yolsuz hem gateway hata yollu uçta döndü.
+- **Gateway zinciri okur (yalnız 5xx):** `microservice_execute`/`debug`/`preview` `runtimeErrors`'a
+  `hata gövdesi — hata yolu: 'callChild' (workflow) → 'childBoom' (code) · 'childBoom' (code)
+  JavaScriptException: …` satırını ekler (debug ucunun `{ data, executionItems }` sarmalı açılır);
+  fırlatan çağrıların (senkron automation'lı `row_create`, `workflow_preview`…) araç hatası da
+  gövdede bulunan `detail`'i, koddan farklı `type`'ı ve varsa zinciri yazar. 4xx gövdeleri
+  süslenmez — onlar bilinçli iş yanıtıdır.
+- **Eski kayıtlar:** 2026-09-16 öncesi gateway `({ code: error.code, message: error.message })`
+  yazıyordu. Global-error dalının hedefi olan, adı `gatewayOnError[n]`, ifadesi bu metinle AYNEN
+  aynı ve açıklaması gateway'in eski metni (ya da boş) olan adım bir sonraki
+  `workflow_create`/`update`/`patch`/`preview`'da yeni gövdeye yükseltilir (`gatewayNormalized`:
+  "hata gövdesi genişletildi"; önizleme kaydetmez). Yanıta alan eklenir, `code`/`message` değişmez.
+  Açıklaması ya da ifadesi elle değiştirilmiş adıma dokunulmaz; yükseltme açıklamayı da yenilediği
+  için sonradan bilerek eski gövdeye dönen `bodyExpression` bir daha ezilmez.
+- **Dışarı ne verdiğine sen karar verirsin.** Adım adları iç yapıyı, `detail` iç istisna mesajını
+  (kısıt adı, host) gösterebilir. **Middleware'in 500 gövdesi korumalı uçların anonim çağıranına da
+  gider** (`ExecuteMicroserviceBehavior`). Herkese açık yüzeyde istemiyorsan hata adımının
+  `bodyExpression`'ını daralt, örn. `({ code: error.code, message: error.message })`.
 
 Global-error dalında `error` değişkeni tanımlıdır:
 
 ```jsonc
 { "code": "RowAlreadyExists", "message": "…", "detail": "…", "type": "…",
-  "step": { "id": "…", "name": "writeRow", "type": "table", "data": …, "input": [ … ] } }
+  "step": { "id": "…", "name": "writeRow", "type": "table", "data": …, "input": [ … ] },
+  "cause": null }   // alt akış / loop iterasyonunda { code, message, detail, type, step: { name, type }, cause }
 ```
 
-`error.step` hangi adımın patladığını söyler — hata yanıtına koymadan önce iki kez düşün, iç
-yapıyı dışarı sızdırır.
+Fail dalında aynı zincir `<adım adı>.error.cause`'tadır (`<adım adı>.error` = `{ code, message, detail,
+type, cause }`).
+
+`error.step` hangi adımın patladığını söyler. `input`/`data` alanları ifade değerlerini ve adım
+çıktısını taşır — gövdeye yalnız ihtiyaç duyduğun alt kümeyi yaz (gateway'in varsayılanı
+`{ name, type }`'tır, yukarıdaki §`gatewayOnError`'un 500 gövdesi).
 
 **Kurallar ve sınırlar:**
 
@@ -257,9 +306,14 @@ yapıyı dışarı sızdırır.
   bağlı — §izin matrisi) ya da `email`/`table` adımına bağla. Bağlı hata yolu yoksa `WF-021` uyarır.
 - **Hata yolu hiç yoksa** (fail dalı ve global-error dalı bağlı değil) adım patladığında motor
   canlıda `WorkflowStepFailedException` fırlatır (2026-09-16): HTTP yanıt 500 +
-  `{ code, message, detail, type }` (patlayan adımın hatası), zamanlanmış iş ve automation geçmişi
-  `failed` + `Step 'x' failed: <sebep>`, senkron automation tetikleyen satır yazımını düşürür.
-  Önizlemede fırlatmaz, ağaç döner. Çalışır, ama çıktı lokalize değildir.
+  `{ code, message, detail, type, step: { name, type }, cause }` — `step` ve `cause` 2026-09-17'den
+  beri, gateway hata adımıyla aynı şekil (yerel ortamda ayrıca `stackTrace`). Zamanlanmış iş ve
+  automation geçmişi `failed` + `Step 'x' failed: <sebep>`, senkron automation tetikleyen satır
+  yazımını düşürür. Önizlemede fırlatmaz, ağaç döner. Çalışır, ama çıktı lokalize değildir.
+- **Adım hata yolunun DIŞINDA patlarsa** (ör. `revert`'in `revertType` ifadesi tırnaksız) kod
+  `EvaluateWorkflowStepFailedException`, mesaj `Step '<ad>' threw outside its error path: <sebep>`
+  olur: fail dalı ve global-error dalı ÇALIŞMAZ, canlı koşu düşer. 2026-09-17'den beri önizleme
+  ağacı kaybolmaz; adım `hasError: true` ile işaretlenir.
 
 > **Preview HTTP 200 dönerken bile akış patlamış olabilir.** `executionSuccess` yalnız SON adıma
 > bakar; ortada patlayıp hata dalından dönen akış `true` gösterir. Gateway tüm adımları (iç içe
@@ -347,6 +401,63 @@ gidilir, hiçbiri tutmazsa `else` dalı yürür:
 > `rule.isExpression` bayrağı bu iki alan için **okunmaz**.
 
 
+## Workflow adımı: başka bir akışı parametreyle çağırmak (WF-032)
+
+Ortak mantığı (kayıt açma, bildirim, numaralandırma) **bir kez** `type:'workflow'` akışı olarak
+yazıp diğer akışlardan çağırmanın yolu budur — 30 adımı kopyalamak değil. Adım tipi `workflow`;
+üç akış tipinde de kullanılabilir. Kuralı **iki alan** taşır ve girdi eşlemesi ikincisidir:
+
+```jsonc
+{ "id": "<GUID>", "name": "createTicket", "type": "workflow",
+  "description": "Telemetri olayından create-ticket akışıyla kayıt açar.",
+  "rule": {
+    "workflowId": "<create-ticket akışının id'si>",
+    "expression": "({ title: input.title, source: 'telemetry', payload: parseEvent.data })"
+  },
+  "branches": [
+    { "id": "<GUID>", "name": "success", "type": "success", "nextStepId": "<sonraki>" },
+    { "id": "<GUID>", "name": "fail", "type": "fail", "nextStepId": "<hata adımı>" }
+  ] }
+```
+
+- **Eşleme `rule.expression`'daki nesne literalidir: her anahtar çağrılan akışın parametre
+  DTO'sundaki bir alan, her değer bir JS ifadesi** (`input.x`, önceki adımın `<ad>.data.x`'i,
+  sabit). Studio'nun adım editörü de aynı şeyi yapar — akış seçilince ifadeyi `parameterScheme`'den
+  `{ "alan": <örnek> }` olarak doldurur (`WorkflowTrigger.svelte`). Table adımının `fields[]`
+  listesinin buradaki karşılığı budur; ayrı bir liste alanı **yoktur** ve gerekmez.
+- **Çağrılan akışın `parameterDtoId` + `parameterBehavior`'ı OLMAK ZORUNDA.** `WorkflowStep`
+  ifadeyi yalnız `workflow.HasParameter` iken değerlendirir (`WorkflowStep.cs`); DTO'suz alt
+  akışa yazılan ifade hiç koşmaz, alt akış boş `input` ile çalışır ve **200 döner**. Gateway
+  çağrılan akışı okuyup bunu **block** eder (WF-032). Reçete: `dto_create` → `workflow_patch(id:
+  <alt akış>, ops: [{ op: 'add', path: '/parameterDtoId', value: <dtoId> }, { op: 'add', path:
+  '/parameterBehavior', value: 'object' }])`.
+- **Başka hiçbir alan girdi taşımaz.** Şema üyeleri (`payloadExpression`, `customParameters`,
+  `queryParameters`, `bodyExpression`, `fields`) kaydedilir ama `WorkflowStep` okumaz; şema dışı
+  adlar (`parameters`, `input`, `payload`, `args`…) platformda hiç kaydedilmez (`unmappedMembers`).
+  İki durumda da alt akış boş girdi alır (RFQ koşusu W-7, 2026-09-14: beş biçim denendi, beşinde
+  de boş girdi). Gateway DOLU değer görürse block eder; `workflow_get`'in geri okuttuğu
+  `fields: []` / `customParameters: null` gibi boş varsayılanlar kuralı tetiklemez.
+- **Ad tuzağı:** `rule.expression` `code` adımında GÖVDE (çalıştırılan kod), `workflow` ve
+  `microfunction` adımında GİRDİ (argüman nesnesi) demektir. Aynı ad, iki anlam.
+- **Alt akış girdiyi `input.<alan>` ile okur ve onun `input`'u bu nesnedir** — çağıranın
+  `input`'unu görmez; çağıranın bir alanı gerekiyorsa eşlemeye koy. `parameterBehavior: 'array'`
+  ise ifade dizi üretmelidir (gateway nesne literali görürse uyarır).
+- **Çıktı alt akışın yanıt gövdesidir** (`response` adımının `returnDtoId` süzgecinden geçmiş
+  hâli) ve sonraki adımlara `<adım adı>.data` ile akar. Alt akış 2xx dışı dönerse ya da bir
+  adımı düşerse çağıran adım **fail** dalına gider; `<adım adı>.data` o zaman alt akışın hata
+  gövdesidir.
+- **Şekli tahmin etme, oku:** `workflow_step_schema(step)` çağrılan akışın `parameterScheme` ve
+  `returnScheme`'ini döner; ya da `workflow_get(<workflowId>)` → `parameterDtoId` → `dto_get`.
+- **Loop içinde:** `rule.stepType: 'workflow'`, `rule.arrayExpression`, çocuk kural
+  `rule.stepRule: { workflowId, expression: "({ title: loopItem.title })" }` — WF-032 çocuğu da
+  denetler.
+- **Önizlemede** alt akışın kendi adım izi `steps[].children[]` altında `kind: 'subWorkflow'` ile
+  gelir; çağıran adımın `input[]` listesinde `member: 'parameter'` satırı ifadenin ürettiği nesneyi
+  gösterir — **satır yoksa ya da değeri boşsa girdi bağlanmamıştır.** Alt akışı tek başına
+  sınamak için kendi `previewPayload`'ı ile `workflow_preview` çağır.
+- Aynı alt akışı birden çok adımdan çağırmak serbesttir; özyineleme runner'ın koşum sayacına
+  takılır (kural envanteri WF-028 — gateway kuralı değil, backend davranışı).
+
 ## Loop step — dizinin her öğesi için bir adım koştur
 
 Tek uçta "başlık + N alt kayıt" yazmanın yolu budur (anket + sorular + seçenekler tek çağrıda;

package/dist/tools/automations.js

@@ -2,7 +2,7 @@ import { guid, entityRef, resolveEntityId, withResolved, projectParam, environme
 import { RefResolver } from '../platform/refs.js';
 import { normalizeWorkflowDefinition, withNormalization } from '../knowledge/normalize.js';
 import { evaluatePolicy, enforcePolicy, attachFindings } from '../knowledge/policy.js';
-import { policyRules, microfunctionStepFindings } from '../knowledge/rules.js';
+import { policyRules, microfunctionStepFindings, workflowStepFindings } from '../knowledge/rules.js';
 import { languageHeader } from '../knowledge/languageCodes.js';
 import { handle } from '../platform/responses.js';
 import { z } from 'zod';
@@ -40,7 +40,8 @@ export function registerAutomationTools(server, platform) {
         const normalized = normalizeWorkflowDefinition(definition);
         const findings = enforcePolicy([
             ...evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'create', workflowKind: 'automation' }, policyOverride),
-            ...await microfunctionStepFindings(platform, project, environment, definition, 'automation', policyOverride)
+            ...await microfunctionStepFindings(platform, project, environment, definition, 'automation', policyOverride),
+            ...await workflowStepFindings(platform, project, environment, undefined, definition, 'automation', policyOverride)
         ]);
         const resolver = new RefResolver(platform, project, environment);
         const resolvedEntityId = await resolveEntityId(resolver, entityId);
@@ -56,7 +57,8 @@ export function registerAutomationTools(server, platform) {
         const normalized = normalizeWorkflowDefinition(definition);
         const findings = enforcePolicy([
             ...evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'update', workflowKind: 'automation' }, policyOverride),
-            ...await microfunctionStepFindings(platform, project, environment, definition, 'automation', policyOverride)
+            ...await microfunctionStepFindings(platform, project, environment, definition, 'automation', policyOverride),
+            ...await workflowStepFindings(platform, project, environment, undefined, definition, 'automation', policyOverride)
         ]);
         const resolver = new RefResolver(platform, project, environment);
         const resolvedEntityId = await resolveEntityId(resolver, entityId);
@@ -135,7 +137,8 @@ export function registerAutomationTools(server, platform) {
         const normalized = normalizeWorkflowDefinition(definition);
         const findings = enforcePolicy([
             ...evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'preview', workflowKind: 'automation' }, policyOverride),
-            ...await microfunctionStepFindings(platform, project, environment, definition, 'automation', policyOverride)
+            ...await microfunctionStepFindings(platform, project, environment, definition, 'automation', policyOverride),
+            ...await workflowStepFindings(platform, project, environment, undefined, definition, 'automation', policyOverride)
         ]);
         const resolver = new RefResolver(platform, project, environment);
         const resolvedEntityId = await resolveEntityId(resolver, entityId);