@appaflytech/zeyrek-ai-mcp 0.0.9 → 0.0.11

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/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/tools/flows.js

@@ -1,7 +1,7 @@
 import { fetchHost, flowPath, hostParam, unwrap } from './screens.js';
 import { guid, projectParam, environmentParam, readOnly, writes, updates, destructive, microOps } from './common.js';
 import { evaluatePolicy, enforcePolicy, attachFindings } from '../knowledge/policy.js';
-import { normalizeFlowSteps, targetlessSetterWarnings, unknownSetterTargetWarnings, withNormalization } from '../knowledge/normalize.js';
+import { flowBindings, normalizeFlowSteps, targetlessSetterWarnings, unknownSetterTargetWarnings, withNormalization } from '../knowledge/normalize.js';
 import { flowBodyWarnings } from '../knowledge/coverage.js';
 import { PlatformApiError } from '../platform/errors.js';
 import { handle } from '../platform/responses.js';
@@ -50,6 +50,90 @@ function flowSummary(flow) {
 function hostNodes(record) {
     return record.schema ?? record.views ?? [];
 }
+const BINDINGS_UNAVAILABLE = 'Barındırıcı kaydı okunamadığı için olay bağları hesaplanamadı; akış listesi yine de günceldir.';
+/**
+ * Akış listesine bağları ekler. `danglingBindings` ters yönü söyler: şemada id'si geçen ama
+ * barındırıcıda karşılığı olmayan akış — olay tetiklenir, hiçbir şey koşmaz.
+ */
+function flowListResult(flows, record) {
+    if (record === undefined)
+        return { flows: flows.map(flowSummary), bindingsNote: BINDINGS_UNAVAILABLE };
+    const bindings = flowBindings(hostNodes(record), record.events);
+    const known = new Set(flows.map(flow => String(flow.id).toLowerCase()));
+    const danglingBindings = [...bindings.entries()]
+        .filter(([flowId]) => !known.has(flowId))
+        .flatMap(([flowId, entries]) => entries.map(entry => ({ flowId, ...entry })));
+    return {
+        flows: flows.map(flow => ({ ...flowSummary(flow), bindings: bindings.get(String(flow.id).toLowerCase()) ?? [] })),
+        unboundFlowIds: flows.map(flow => String(flow.id)).filter(flowId => !bindings.has(flowId.toLowerCase())),
+        ...(danglingBindings.length > 0 ? { danglingBindings } : {})
+    };
+}
+const ifExistsParam = z.enum(['error', 'update', 'duplicate']).default('error').describe("Barındırıcıda aynı ad ya da slug'da (büyük/küçük harf duyarsız) akış varsa ne olacağı. 'error' (varsayılan): yazmaz, mevcut akışın id'sini döner. 'update': mevcut akışı bu gövdeyle günceller (id'si ve olay bağları korunur). 'duplicate': platformun ürün davranışı — ikinci kayıt açılır, platform ada/slug'a ' (1)' sayacını ekler (Studio'daki 'New Flow (1)' ile aynı kural).");
+const upper = (value) => String(value ?? '').toUpperCase();
+/**
+ * Barındırıcının akışları, önbelleksiz liste ucundan (`GET /pages|layouts/{id}/flows`). Layout ve
+ * sayfa tasarım kaydı önbellekten gelir ve zarfsız akış yazmasından sonra akışı hemen taşımaz;
+ * 2026-09-16 raporundaki kopyalar bu yüzden doğdu. Widget kaydı önbelleksizdir, oradan okunur.
+ * Layout ucu olmayan eski backend 404/405 verir: o zaman kayda düşülür.
+ */
+async function listHostFlows(platform, host, project, environment, applicationId, hostId, hostRecord) {
+    if (host !== 'component') {
+        try {
+            const payload = await platform.tenant('GET', project, flowPath(host, applicationId, hostId), { environment });
+            if (!Array.isArray(payload?.data))
+                throw new PlatformApiError('akış listesi yanıtında data dizisi yok');
+            return payload.data;
+        }
+        catch (error) {
+            const status = error instanceof PlatformApiError ? error.status : undefined;
+            if (host === 'page' || (status !== 404 && status !== 405))
+                throw error;
+        }
+    }
+    const record = await hostRecord();
+    return Array.isArray(record.flows) ? record.flows : [];
+}
+/**
+ * FLOW-026 kapısı. Aynı adla ikinci akışın `"<ad> (1)"` olarak açılması platformun ürün kararıdır
+ * (`FlowService.MakeNameUniqueAsync`; Studio'da da sayfa/workflow/akış aynı kuralla adlanır) ve
+ * değişmez. MCP ajanı ise çağrıyı tekrar edebildiği için varsayılanı "yazma, mevcut id'yi söyle"dir.
+ * Aday araması platformda `LIKE` ile harfe duyarlıdır; gateway bilinçli olarak harf duyarsız
+ * karşılaştırır. Var-mı okuması başarısız olursa çağrı düşer — okuyamadığı listeyi boş sayan kontrol
+ * tam da zaman aşımında kopya üretirdi.
+ */
+async function existingFlowMatch(platform, host, project, environment, applicationId, hostId, hostRecord, name, slug, flowId, ifExists) {
+    if (ifExists === 'duplicate')
+        return undefined;
+    let flows;
+    try {
+        flows = await listHostFlows(platform, host, project, environment, applicationId, hostId, async () => hostRecord);
+    }
+    catch (error) {
+        throw new PlatformApiError(`FLOW-026: barındırıcının mevcut akışları okunamadı, akış YAZILMADI (${error instanceof Error ? error.message : String(error)}). Liste okunmadan yazmak aynı adla ikinci akış açabilir; flow_list ile tekrar deneyin ya da bilerek ikinci akış istiyorsanız ifExists:'duplicate' verin.`);
+    }
+    const matches = flows.filter(flow => upper(flow.name) === upper(name) || upper(flow.slug) === upper(slug));
+    const [match] = matches;
+    if (match === undefined)
+        return undefined;
+    const describe = (flow) => `${String(flow.id)} ('${String(flow.name)}', slug '${String(flow.slug)}')`;
+    const copyPattern = new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} \\(\\d+\\)$`, 'i');
+    const copies = flows.filter(flow => copyPattern.test(String(flow.name ?? '')));
+    const copyNote = copies.length > 0
+        ? ` Barındırıcıda bu adın sayaçlı eşleri de var: ${copies.map(describe).join(' · ')} — bağı olup olmadığını flow_list (bindings) ile kontrol edip gerekirse silin.`
+        : '';
+    if (ifExists === 'error') {
+        const where = host === 'page' ? 'sayfada' : host === 'layout' ? "layout'ta" : "widget'ta";
+        throw new PlatformApiError(`FLOW-026: bu ${where} aynı ad ya da slug'da akış zaten var: ${matches.map(describe).join(' · ')}. İstek gönderilmedi — gönderilseydi platform ürün kuralı gereği ikinci bir akış açardı (çakışan ad ya da slug'a ' (1)' sayacı eklenerek; yalnız harf farkı varsa sayaçsız). Mevcut akışı güncellemek için aynı çağrıyı ifExists:'update' ile tekrarlayın; bilerek ikinci akış istiyorsanız ifExists:'duplicate'.${copyNote}`, 409);
+    }
+    if (matches.length > 1) {
+        throw new PlatformApiError(`FLOW-026: ad ve slug farklı akışlara çıkıyor (${matches.map(describe).join(' · ')}); hangisinin güncelleneceği belirsiz, istek gönderilmedi. flowId ile flow_update kullanın.${copyNote}`, 409);
+    }
+    if (flowId !== undefined && flowId.toLowerCase() !== String(match.id).toLowerCase()) {
+        throw new PlatformApiError(`FLOW-026: verilen flowId (${flowId}) aynı adlı mevcut akışla (${describe(match)}) çelişiyor; istek gönderilmedi. Mevcut akışı güncellemek için flowId'yi vermeyin ya da ${String(match.id)} verin.`, 409);
+    }
+    return match;
+}
 async function requiredParameterWarnings(platform, project, environment, applicationId, steps) {
     const warnings = [];
     const microserviceSteps = steps
@@ -226,32 +310,41 @@ export function registerFlowTools(server, platform) {
     const config = platform.config;
     server.registerTool('flow_list', {
         title: 'Akışları listele',
-        description: "Barındırıcının olay akışlarını listeler. Sayfada ayrı bir liste ucu vardır; layout ve komponentte akışlar kaydın kendi gövdesinden okunur.",
+        description: "Barındırıcının olay akışlarını, her birine bağlı olaylarla (bindings: [{ target: elementId | 'page', event }]) listeler. unboundFlowIds hiçbir olaya bağlı olmayan (sahipsiz) akışlardır; danglingBindings şemada id'si geçen ama barındırıcıda olmayan akışlardır. Sayfa ve layout akışları önbelleksiz liste ucundan, widget akışları kaydın kendi gövdesinden okunur; bağlar barındırıcının şemasından hesaplanır.",
         inputSchema: { project: projectParam, environment: environmentParam, host: hostParam, applicationId: guid, hostId: guid },
         annotations: readOnly
     }, handle(config, async ({ project, environment, host, applicationId, hostId }) => {
-        if (host === 'page') {
-            const payload = await platform.tenant('GET', project, flowPath('page', applicationId, hostId), { environment });
-            return { flows: (payload?.data ?? []).map(flowSummary) };
+        if (host === 'component') {
+            const record = await fetchHost(platform, host, project, environment, applicationId, hostId);
+            return flowListResult(Array.isArray(record.flows) ? record.flows : [], record);
         }
-        const record = await fetchHost(platform, host, project, environment, applicationId, hostId);
-        return { flows: (Array.isArray(record.flows) ? record.flows : []).map(flowSummary) };
+        let record;
+        const readRecord = async () => (record ??= await fetchHost(platform, host, project, environment, applicationId, hostId));
+        const flows = await listHostFlows(platform, host, project, environment, applicationId, hostId, readRecord);
+        return flowListResult(flows, record ?? await readRecord().catch(() => undefined));
     }));
     server.registerTool('flow_get', {
         title: 'Akış getir',
-        description: "Tek akışı adımlarıyla getirir; yeni akış yazarken en iyi şablon budur. Hedefi silinmiş (element'siz) setter iteratee'si varsa yanıttaki flowWarnings söyler — o adım koşar ama hiçbir şeye yazmaz.",
+        description: "Tek akışı adımlarıyla getirir; yeni akış yazarken en iyi şablon budur. bindings bu akışa bağlı olaylardır ([{ target: elementId | 'page', event }]; boşsa akış sahipsizdir). Hedefi silinmiş (element'siz) setter iteratee'si varsa yanıttaki flowWarnings söyler — o adım koşar ama hiçbir şeye yazmaz.",
         inputSchema: { project: projectParam, environment: environmentParam, host: hostParam, applicationId: guid, hostId: guid, flowId: flowIdParam },
         annotations: readOnly
     }, handle(config, async ({ project, environment, host, applicationId, hostId, flowId }) => {
         const response = await platform.tenant('GET', project, flowPath(host, applicationId, hostId, flowId), { environment });
+        const record = await fetchHost(platform, host, project, environment, applicationId, hostId).catch(() => undefined);
         const warnings = targetlessSetterWarnings(response);
-        if (warnings.length === 0 || !response || typeof response !== 'object' || Array.isArray(response))
+        if (!response || typeof response !== 'object' || Array.isArray(response))
             return response;
-        return { ...response, flowWarnings: warnings };
+        return {
+            ...response,
+            ...(record === undefined
+                ? { bindingsNote: BINDINGS_UNAVAILABLE }
+                : { bindings: flowBindings(hostNodes(record), record.events).get(flowId.toLowerCase()) ?? [] }),
+            ...(warnings.length > 0 ? { flowWarnings: warnings } : {})
+        };
     }));
     server.registerTool('flow_create', {
         title: 'Akış oluştur',
-        description: "Sayfa/layout/komponent için olay akışı oluşturur. İstek yalnız akışı yazar, barındırıcının şemasına dokunmaz; gateway barındırıcıyı yalnız setter hedeflerini denetlemek için okur (FLOW-024). Akışı bir komponent olayına bağlamak ayrı adımdır ve akış kaydedildikten SONRA yapılır: set_event {target, event, eventValue: <flow id>} — sayfada page_schema_patch, layout'ta layout_schema_patch, widget'ta component_schema_patch.",
+        description: "Sayfa/layout/komponent için olay akışı oluşturur. Aynı ad ya da slug'da akış varsa varsayılan olarak YAZMAZ ve mevcut akışın id'sini döner (FLOW-026 — gönderilseydi platform ürün kuralı gereği '<ad> (1)' adıyla ikinci bir akış açardı); tekrar çalıştırılabilir yazma için ifExists:'update' verin, yanıttaki outcome 'created' | 'updated' olur. Mevcut akışlar okunamazsa da yazmaz. İstek yalnız akışı yazar, barındırıcının şemasına dokunmaz; gateway barındırıcıyı setter hedeflerini denetlemek (FLOW-024), mevcut akışları ise önbelleksiz liste ucundan okur. Akışı bir komponent olayına bağlamak ayrı adımdır ve akış kaydedildikten SONRA yapılır: set_event {target, event, eventValue: <flow id>} — sayfada page_schema_patch, layout'ta layout_schema_patch, widget'ta component_schema_patch. Hangi olayların bağlı olduğunu flow_list / flow_get bindings alanı söyler.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
@@ -263,12 +356,13 @@ export function registerFlowTools(server, platform) {
             steps: stepsParam,
             errorSteps: stepsParam.optional(),
             flowId: guid.optional().describe('Verilmezse platform üretir; şemaya önceden bağlamak için kendiniz üretebilirsiniz'),
+            ifExists: ifExistsParam,
             policyOverride: policyOverrideParam
         },
         annotations: writes
-    }, handle(config, async ({ project, environment, host, applicationId, hostId, name, slug, steps, errorSteps, flowId, policyOverride }) => {
+    }, handle(config, async ({ project, environment, host, applicationId, hostId, name, slug, steps, errorSteps, flowId, ifExists, policyOverride }) => {
         const hostRecord = await fetchHost(platform, host, project, environment, applicationId, hostId);
-        const resolvedFlowId = flowId ?? randomUUID();
+        const resolvedFlowId = (flowId ?? randomUUID()).toLowerCase();
         const flow = {
             id: resolvedFlowId,
             name,
@@ -279,6 +373,8 @@ export function registerFlowTools(server, platform) {
         };
         const normalized = [...normalizeFlowSteps(flow.steps), ...normalizeFlowSteps(flow.errorSteps)];
         const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'flow', flow, { operation: 'create' }, policyOverride));
+        const existing = await existingFlowMatch(platform, host, project, environment, applicationId, hostId, hostRecord, name, slug, flowId, ifExists);
+        const writtenFlowId = existing === undefined ? resolvedFlowId : String(existing.id);
         const parameterWarnings = [
             ...await requiredParameterWarnings(platform, project, environment, applicationId, steps),
             ...await functionWarnings(platform, host, project, environment, applicationId, hostId, steps),
@@ -287,15 +383,21 @@ export function registerFlowTools(server, platform) {
         ];
         // Gövde yalnız akıştır (designer-partial-update K1): barındırıcı zarfı platformda hâlâ isteğe bağlı
         // ama gönderilirse okunan tam kaydı yeniden yazar, açık Studio designer'ının kayıtlı tabanını
-        // eskitir. Kayıt yalnız FLOW-024 hedef araması için okunur.
-        await platform.tenant('POST', project, flowPath(host, applicationId, hostId), { environment, body: { flow } });
+        // eskitir. Kayıt FLOW-024 hedef araması ve FLOW-026 var-mı kontrolü için okunur.
+        if (existing === undefined) {
+            await platform.tenant('POST', project, flowPath(host, applicationId, hostId), { environment, body: { flow } });
+        }
+        else {
+            await platform.tenant('PUT', project, flowPath(host, applicationId, hostId, writtenFlowId), { environment, body: { flow: { ...flow, id: writtenFlowId } } });
+        }
         // Diff YALNIZ çağıranın yazdığı alanları kapsar; `id` ve barındırıcı bağı (`pageId` vb.)
         // gövdeye gateway koyar, kullanıcının düzeltebileceği bir şey değildir.
-        const drops = await flowWriteDrops(platform, host, project, environment, applicationId, hostId, resolvedFlowId, { name: flow.name, slug: flow.slug, steps: flow.steps, errorSteps: flow.errorSteps });
+        const drops = await flowWriteDrops(platform, host, project, environment, applicationId, hostId, writtenFlowId, { name: flow.name, slug: flow.slug, steps: flow.steps, errorSteps: flow.errorSteps });
         return attachFindings(withWriteDiff(withNormalization({
             host,
             hostId,
-            flow: { id: resolvedFlowId, name, slug, steps: steps.length },
+            outcome: existing === undefined ? 'created' : 'updated',
+            flow: { id: writtenFlowId, name, slug, steps: steps.length },
             ...(parameterWarnings.length > 0 ? { parameterWarnings } : {}),
             hint: "Akışı bir olaya bağlamak için: page_schema_patch (layout'ta layout_schema_patch, widget'ta component_schema_patch) ops:[{op:'set_event', target:<elementId>, event:'<component_get events listesindeki ad>', eventValue:<flow id>}]. Olay adları komponente özeldir ve 'on' ÖNEKİ ALMAZ (button → 'click', form → 'submit', table → 'mount'/'select'/'sort'…); uydurma ad 200 döner ama bağ sessizce ölü kalır — gateway PAGE-008 ile yakalar."
         }, normalized), drops), findings);

package/dist/tools/pages.js

@@ -19,6 +19,8 @@ import { resolveIdentityToken } from '../platform/tokenVault.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { setPropTypeErrors } from '../knowledge/propTypes.js';
+import { designSnapshotInput } from '../knowledge/designSnapshot.js';
+import { discoverPage } from '../knowledge/pageDiscover.js';
 import { z } from 'zod';
 /**
  * Runtime paketindeki `appFunctions`/`pageFunctions` (UiFunctionRuntimeDto: id, name, parameters,
@@ -800,6 +802,20 @@ export function registerPageTools(server, platform, injectedScreenshotter, injec
             ...flexIndexOrderNote(ordering.moved)
         ]), opDrops);
     }));
+    server.registerTool('page_discover', {
+        title: 'Tasarım ekranından sayfa iskeleti öner',
+        description: "Tasarım anlık görüntüsündeki bir EKRANIN rolünden (list · form · detail · auth · shell — sözleşme platform_guide('theme') §Tasarım dosyasından tema) altın örnek arketipini seçip page_create + page_schema_patch iskeletini döner: pageCreateArgs (ad/slug ekrandan), schemaPatchOps, flows (örneğin akış gövdeleri), presetBindings (theme_discover'ın aynı anlık görüntüden ürettiği adlı preset TEK adaysa props.style.$preset olarak bağlanır), notes (yerleşim + ekran notları), caveats (yer tutucular, doldurulacak alanlar), next (çağrı sırası). shell rolü layout_create iskeleti döner. PİKSEL KOPYASI DEĞİLDİR: iskelet örneğin domainindedir, ajan ekran notlarına göre tamamlar. YAZMAZ, platforma gitmez, tahmin yapmaz.",
+        inputSchema: {
+            snapshot: designSnapshotInput.describe('Tasarım anlık görüntüsü (screens[] dolu olmalı)'),
+            screen: z.string().min(1).describe("screens[] içindeki ekranın nodeId'si ('92:4339') ya da adı ('Deals')"),
+            layoutId: guid.optional().describe('Sayfanın kabuğu (layout_list); verilmezse pageCreateArgs kabuksuz döner ve caveats söyler'),
+            middlewareIds: z.array(guid).optional().describe('Korumalı sayfa için auth middleware id listesi (middleware_list); verilmezse örnekteki yer tutucu düşer ve caveats söyler')
+        },
+        annotations: readOnly
+    }, handle(config, async ({ snapshot, screen, layoutId, middlewareIds }) => discoverPage(snapshot, screen, {
+        ...(layoutId === undefined ? {} : { layoutId }),
+        ...(middlewareIds === undefined ? {} : { middlewareIds })
+    })));
     server.registerTool('page_create', {
         title: 'Sayfa oluştur',
         description: "Yeni sayfa açar. Şemayı burada göndermek yerine boş bırakıp page_schema_patch micro-op'larıyla kurmak daha doğrudur (canlı canvas ve hedefli düzeltme orada). Şemayı burada gönderirseniz 2026-09-08'den beri AYNI doğrulama duvarından geçer: tanınmayan prop adı ve geçersiz enum değeri 422 ile reddedilir ve sayfa HİÇ açılmaz. roleIds için role_list, layoutId için layout_list kullanın. Yanıttaki schema VARSAYILAN OLARAK iskelettir (çözülmüş layout düğümleri dâhil id/type/children'a iner) — tam gövde için view:'full'; gönderdiğiniz bir alan kaydedilmediyse silentlyDropped söyler.",

package/dist/tools/themes.js

@@ -2,6 +2,8 @@ import { guid, projectParam, readOnly, updates } from './common.js';
 import { diffCssVars, mergeRadiusScale, mergeSpacingScale, mergeTypeScale, resolveTheme } from '../knowledge/themeResolve.js';
 import { diffThemePaths, mergeTheme, normalizeTheme, readProjectTheme, summarizeTheme, themeInput, unsetThemePaths } from '../knowledge/themeSchema.js';
 import { componentPresetTypeWarnings, themeInputWarnings, unsetWarnings } from '../knowledge/themeRules.js';
+import { designSnapshotInput } from '../knowledge/designSnapshot.js';
+import { discoverTheme } from '../knowledge/themeDiscover.js';
 import { attachFindings, enforcePolicy, evaluatePolicy, applyPolicyMode } from '../knowledge/policy.js';
 import { projectUpdateForm } from './projects.js';
 import { withNormalization } from '../knowledge/normalize.js';
@@ -90,6 +92,56 @@ export function registerThemeTools(server, platform) {
             note: "Değerlerin ekrana indiği hâl için view:'resolved'; yazmak için theme_update (kısmi günceller, lint'ten geçirir, hangi CSS değişkeninin değiştiğini söyler). Adlı bir preset'i düğüme bağlamak: style.$preset — platform_guide('theme')."
         };
     }));
+    server.registerTool('theme_discover', {
+        title: 'Tasarım anlık görüntüsünden tema öner',
+        description: "Bir tasarım anlık görüntüsünü (Figma değişkenleri, metin stilleri, gölgeler, bileşen ölçüleri — sözleşme platform_guide('theme') §Tasarım dosyasından tema, altın örnek design-snapshot) theme_update şemasında bir tema önerisine çevirir ve HESABINI verir: mapping (hangi ad hangi yola, hangi kuralla), unmapped (neden gitmedi), gaps (kaynağı olmayan alan), lint uyarıları; project verilirse mevcut temaya göre changed + cssVarsChanged önizlemesi. YAZMAZ — yazmak için theme_update({ theme }), önce dryRun. Eşleme ad temelli ve deterministiktir, tahmin yapmaz: eşlenmeyen token için kararı anlık görüntünün hints alanına yazarsınız ve karar dosyada kalır — Figma'ya ikinci kez gidilmez. Yalnız sapan değer yazılır: platform varsayılanına eşit taban ve ±0,05 içindeki oran öneriye girmez.",
+        inputSchema: {
+            snapshot: designSnapshotInput.describe("Tasarım anlık görüntüsü — sözleşme platform_guide('theme') §Tasarım dosyasından tema; her seviyede strict, tanınmayan anahtar reddedilir. variables get_variable_defs çıktısının kendisidir; hints: Figma adı → tema yolu (accent.muted, paletteDark.accent.primary, colors.blue.500) ya da 'ignore'"),
+            project: projectParam.describe("Yalnız ÖNİZLEME için: verilirse projenin mevcut teması okunur (GET) ve öneri ona derin birleştirilerek changed + cssVarsChanged hesaplanır. Verilmezse platforma HİÇ gidilmez — DefaultProject burada devreye girmez"),
+            deriveDark: z.boolean().optional().describe("true: anlık görüntüde koyu küme (variablesDark) YOKSA paletteDark aydınlık accent/status değerlerinden deterministik karışımla türetilir ve her değer mapping.via:'derived' ile işaretlenir — marka kararı değil başlangıç noktası. variablesDark varsa bayrak yok sayılır. Varsayılan: türetme yok (gaps: paletteDark, THEME-009)")
+        },
+        annotations: readOnly
+    }, handle(config, async ({ snapshot, project, deriveDark }) => {
+        const discovered = discoverTheme(snapshot, { deriveDark: deriveDark === true });
+        const proposal = normalizeTheme(discovered.theme);
+        const fixes = [...discovered.normalized, ...proposal.fixes];
+        let preview;
+        let merged = proposal.theme;
+        if (project !== undefined) {
+            const { project: projectInfo, theme: base } = await loadProject(platform, project);
+            const current = base ?? {};
+            merged = normalizeTheme(mergeTheme(current, proposal.theme)).theme;
+            preview = {
+                project: projectInfo,
+                changed: diffThemePaths(current, merged),
+                cssVarsChanged: diffCssVars(resolveTheme(current).cssVars, resolveTheme(merged).cssVars),
+                note: 'theme_update({ theme, dryRun: true }) aynı sonucu verir; bu önizleme yalnız GET ile hesaplandı, hiçbir şey yazılmadı.'
+            };
+        }
+        // Uyarılar YAZMA anındaki kurallarla aynı motordan (THEME-005/008/009 …): ajan öneriyi
+        // theme_update'e taşımadan ne uyarı alacağını burada görür. Block kuralları da listelenir ama
+        // enforce edilmez — bu tool yazmıyor; yazma anında theme_update durdurur. Operasyon 'update'
+        // çünkü tema kuralları yalnız ona kayıtlı (`appliesTo: ['update']`); 'preview' ile hiçbiri
+        // değerlendirilmiyordu (inceleme B-7). Sorulan şey aynı: "bu kayıt yazılsa geçer mi".
+        const findings = config.policyMode === 'off'
+            ? []
+            : applyPolicyMode(config, [
+                ...evaluatePolicy(config, policyRules, 'theme', merged, { operation: 'update' }),
+                ...themeInputWarnings(proposal.theme, merged)
+            ]);
+        const empty = Object.keys(proposal.theme).length === 0;
+        return attachFindings(withNormalization({
+            source: snapshot.source,
+            theme: proposal.theme,
+            mapping: discovered.mapping,
+            unmapped: discovered.unmapped,
+            gaps: discovered.gaps,
+            ...(preview === undefined ? {} : { preview }),
+            note: empty
+                ? 'Anlık görüntüde eşlenebilir token yok — unmapped (sebep) ve gaps (kaynağı olmayan alan) listelerine bakın; kararı hints ile verin.'
+                : "Yazmak için theme_update({ theme }) — önce dryRun: true. unmapped kararlarını anlık görüntünün hints alanına yazın ve dosyayı koşu klasöründe bırakın; ikinci koşu Figma'ya dönmez. gaps'teki alanlar uydurulmadı: kaynağı ekleyin ya da boş bırakın."
+        }, fixes), findings);
+    }));
     server.registerTool('theme_update', {
         title: 'Proje temasını güncelle',
         description: "Temayı KISMİ günceller: kaydı okur, verdiğiniz alanları derin birleştirir, normalize eder, lint'ten geçirir ve yazar — bir rengi değiştirmek preset'leri ve bileşen preset'lerini düşürmez. Yanıt hangi yolların değiştiğini (changed) ve hangi CSS değişkeninin hangi değerden hangi değere gittiğini (cssVarsChanged) söyler; dryRun ile yazmadan aynı yanıtı alırsınız. DİKKAT: tema PROJE kaydıdır — değişiklik BÜTÜN ortamların runtime'ına iner (production dâhil) ve Studio tema paneli açık ve kaydedilmemişse panelin sonraki Save'i bu yazmayı ezer.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appaflytech/zeyrek-ai-mcp",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "description": "Zeyrek (NgApps) platform APIs as MCP tools — data, logic and Studio design surface in one gateway",
   "license": "UNLICENSED",
@@ -54,4 +54,4 @@
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"
   }
-}
+}