@appaflytech/zeyrek-ai-mcp 0.0.3 → 0.0.4

package/dist/resources/guides/layout.md

@@ -0,0 +1,147 @@
+# Layout Rehberi (yerleşim kabuğu)
+
+Sayfaların paylaştığı kabuk: yan menü, üst şerit, kullanıcı menüsü ve sayfa içeriğinin
+gireceği delik. Şema gövdesi ve koordinat modeli için `platform_guide('page')` (Kural 1,
+1d, 1f); komponent sözleşmeleri için `platform_guide('component')`.
+
+## Karar kuralları
+
+**1. Layout, tek `slot` içeren SIRADAN bir komponent ağacıdır.** Ayrı bir dil yoktur:
+sayfada kullandığın her kap, her prop, her `appearance` alanı burada da geçerlidir. Araç
+kutusu layout modülünde süzülmez — tüm katalog kullanılabilir.
+
+**2. Şema alanının adı `schema` değil `views`.** (LAY-001)
+
+**3. Micro-op hattı YOKTUR.** `page_schema_patch`'in layout karşılığı yok (backend'de
+`PATCH /layouts/.../schema` ucu yok). Değişiklik `layout_update` ile yazılır; gateway kaydı
+önce okur ve yalnız verdiğin alanları değiştirir, `views` göndermezsen ağaç korunur.
+Okumak için `layout_schema_get` (summary kipi hedef bulmak için yeterlidir).
+
+**4. TEK slot.** Sayfa şeması **her** slot'a ayrı ayrı kopyalanır — iki slot, sayfayı iki
+kez çizer ve `elementId`'leri tekrarlar. (LAY-002 / LAY-006)
+
+**5. Kabuğu `container` + `slot` ile kur.** `layout` monoliti (sabit logo/menü/kullanıcı
+bandı — yalnız doldurulur) ve `layout-shell` + `layout-region` ikilisi **emekliye
+ayrıldı**; kayıtlı kalırlar ve mevcut layout'lar çalışır, ama yeni kabuk `container` ile
+kurulur. Sebebi: `container` zaten `layout-region`'ın yaptığının üstünü yapıyor (flex/ızgara
+düzeni, hizalama, gap, wrap), region'ın kattığı tek şey `dock` sözlüğüydü.
+
+**5a. Kök, sayfanın `page_container`'ının yerleşim ikizidir.** Studio'nun yeni layout
+iskeleti (`getDefaultLayout`) tam olarak şunu kurar ve sen de aynısını yazmalısın:
+`states.isWrapper: true` (çerçevesiz, başlıksız, saydam) + `appearance.heightType: 'fill'`
++ `blocks` x0/w12. Sarmalayıcı olmayan bir kök, kenarlıklı beyaz bir kart olarak çizilir.
+
+**5b. Tam ekran kabuk `heightType: 'fill'` ile kurulur (2026-08-28).** Yükseklik ne
+içerikten (`auto`) ne satır sayısından (`fixed`) gelir — ebeveynin bıraktığı yerden gelir:
+ızgara çocuğunda `height:100%`, flex sütununda `flex:1 1 auto`, flex satırında
+`align-self:stretch`. **Kök** düğümde ekranı doldurur (100vh). Yan menünün tam boy olması
+ve slot'un artan alanı kaplaması bununla ifade edilir; `fixed` + tahmini `size.h` ile
+yapılan eski numaraya artık gerek yok.
+
+**6. Konum `blocks[]`'ten gelir, prop'tan değil.** `layout-region`'daki `dock` bölgenin
+NEREDE durduğunu değil, BİÇİMİNİ söyler (dikey kolon / yatay şerit / dolgu yüzeyi). Hem
+runtime hem Studio tuvali bölgeleri 12 kolonluk ızgarayla yerleştirir.
+
+**7. Mobilde flex YIĞILMAZ.** Runtime'ın mobil kuralı yalnız ızgara özelliklerini ezer.
+Telefonda alt alta düşmesi gereken satırı `layout:'grid'` ile kur; `layout:'flex'` +
+`direction:'row'` telefonda da yan yana kalır (375px'te ölçüldü: ızgara çocukları 375/375px
+alt alta, flex çocukları 49/310px yan yana).
+
+**8. Doğrulama tek yerden:** `page_runtime_get`. Layout'un kendi serve URL'i yoktur —
+gerçek çıktıyı, layout'a bağlı bir sayfanın runtime paketinde görürsün (slot yerleşimi
+dahil). Slot kurgusu için ayrıca `page_state` → `layoutSlots`.
+
+## Mini tarif — uygulama kabuğu
+
+Yan menü + üst şerit + içerik. Studio'nun `getDefaultLayout` iskeletiyle birebir aynı ağaç;
+`layout_create`'in `views` alanına doğrudan verilebilir (`resource: layout-app-shell`).
+
+```
+container  isWrapper:true  heightType:'fill'  layout:'flex' direction:'row' gap:'none'
+│                                             verticalAlign:'stretch'   block w12 x0
+├ container  heightType:'fill'  layout:'flex' direction:'column'         block w2   ← yan menü
+│  └ navigations                                                         block w12
+└ container  heightType:'fill'  layout:'flex' direction:'column'         block w10 x2
+   ├ container  layout:'flex' direction:'row'  states.isSticky           block w12 h6
+   │  └ breadcrumb                                                       block w12 h3
+   └ slot       heightType:'fill'                                        block w12 y6
+```
+
+- **Genişlik kolon payıdır:** yan menü `w:2` = 12'de 2 → 1440px tasarım genişliğinde 240px.
+  Sabit piksel istiyorsan `appearance.widthPx: 240` (yalnız flex çocuğunda okunur; ızgara
+  kabında okunmaz).
+- **Yükseklik `fill`'dir**, `size.h` değil: kök ekranı doldurur, yan menü ve içerik sütunu
+  kökün bıraktığını, slot da üst şeritten artanı alır. Slot'un grid satırı ayrıca açık
+  uçludur (`y / auto`), yani sayfa uzadıkça slot uzar.
+- **Kaydırma:** `fill` + `states.isScrollable:true` verilen düğüm büyümek yerine İÇİNDE
+  kaydırır — uzun içerikte kabuğu sabit tutmanın yolu budur.
+- **MOBİL UYARISI:** bu ağaç `flex` olduğu için telefonda YIĞILMAZ (Kural 7) — 375px'te yan
+  menü ince bir şerite iner. Telefonda alt alta düşmesi gereken bir kabuk için kökü
+  `layout:'grid'` kur; o zaman `fill`'in flex anlamı (`flex:1 1 auto`) devreye girmez,
+  yükseklik yine `blocks` satırlarından gelir. İkisini aynı anda veren bir yol bugün yok.
+- Menü satırlarını biçimlendirme: **bugün mümkün değil.** `navigations`'ın `style` prop'u
+  ölüdür (bkz. `component_get('navigations')`).
+
+## Mini tarif — menüde aktif satır
+
+`navigations.activeHref` boş bırakılırsa menü tarayıcıdaki adrese uyan satırı kendi bulur;
+hiç ayar gerekmez. Elle sürmek istersen satırın `href`'iyle aynı biçimde yaz (ham metin,
+bağlantı nesnesi ya da tam yol).
+
+## Kötü / iyi
+
+```jsonc
+// KÖTÜ — iki slot: sayfa iki kez çizilir, elementId'ler çakışır
+{ "views": [{ "type": "container", "children": [
+  { "type": "slot" }, { "type": "slot" }
+]}]}
+
+// KÖTÜ — sarmalayıcı olmayan, sabit yükseklikli kök: ekranı doldurmaz,
+// kenarlıklı beyaz bir kart olarak çizilir ve yüksekliği tahmini h'den gelir
+{ "type": "container", "states": { "isDroppable": true },
+  "appearance": { "heightType": "fixed" },
+  "blocks": [{ "breakpoint": 1024, "size": { "w": 7, "h": 83 }, "position": { "x": 2, "y": 0 } }] }
+
+// İYİ — sarmalayıcı, tam genişlikte, ekranı dolduran kök (Kural 5a/5b)
+{ "type": "container",
+  "states": { "isDroppable": true, "isWrapper": true },
+  "appearance": { "heightType": "fill", "marginType": "none", "paddingType": "none" },
+  "props": { "layout": { "type": "static", "data": "flex" },
+             "direction": { "type": "static", "data": "row" } },
+  "blocks": [{ "breakpoint": 1024, "size": { "w": 12, "h": 80 }, "position": { "x": 0, "y": 0 } }] }
+
+// KÖTÜ — telefonda 49px'lik yan menü: row flex mobilde yığılmaz (Kural 7)
+// Mobilde alt alta düşmesi gerekiyorsa kökü layout:'grid' kur — bedeli, fill'in
+// flex anlamının devreye girmemesi.
+```
+
+## Sayfayı layout'a bağlama
+
+`page_update` ile `layoutId`. Bağlı sayfanın kendi şeması slot'un içine girer; sayfanın
+kök `page_container`'ı korunur.
+
+## Bilinen boşluklar (2026-08-28)
+
+Bunlar **motorun** eksikleri, senin hatan değil — bir tasarımı karşılayamıyorsan sebebi
+bunlardan biri olabilir:
+
+| Eksik | Sonuç |
+|---|---|
+| ~~`heightType` yalnız `auto` \| `fixed`~~ | **28 Ağustos'ta kapandı:** üçüncü değer `fill` (Kural 5b) |
+| ~~Kök kap viewport'a kilitlenmez~~ | **28 Ağustos'ta kapandı:** `fill` verilmiş kök 100vh (Kural 5b) |
+| Flex mobilde yığılmaz | Kural 7 — kabuk bugün bir MASAÜSTÜ kabuğudur |
+| Kırılıma duyarlı prop yok | `direction`/`gap` masaüstü ve mobilde AYNI; yalnız `blocks` ve `appearance.hideOn` kırılım bilir |
+| Mobil çekmece (overlay) yok | Telefonda içeriğin üstüne binen panel kurulamaz |
+
+---
+
+**Kaynaklar** — `zeyrek-frontend`: `apps/studio/src/features/layout/layout.functions.ts`
+(`injectPageSchemaIntoSlots`, `getResolvedLayoutViews`), `apps/studio/src/features/page/api/page.mappers.ts`
+(`mapPageLayoutToPreview`), `packages/ng-apps-ui/src/shared/render/render.functions.ts`
+(`resolveNodeBoxStyle` — slot'un `y / auto` satırı, flex çocuk genişliği),
+`packages/ng-apps-ui/src/shared/render/RenderComponent.svelte` (mobil media kuralı),
+`packages/ng-apps-screen-builder/src/flex-layout.ts` (`getFlexChildStyle` — `widthPx` ve
+`heightType:'fill'` dalı; tuval ve runtime aynı fonksiyonu okur),
+`apps/studio/src/features/layout/layout.functions.ts` (`getDefaultLayout` — Kural 5a/5b'deki iskelet),
+`docs/components/layout-composition.md`, `docs/specs/2026-08-28-free-layout-responsive-design.md`,
+`docs/issues.md` ARC-031 / BE-002 / CQ-143.

package/dist/resources/guides/microservice.md

@@ -1,5 +1,38 @@
 # Microservice Rehberi
 
+## Ucun NE İŞE YARADIĞI yazılır (MS-014, block)
+
+Servis listesinde `name` ve `slug` var, "bu uç ne işe yarar" yok. Her microservice bir
+`description` taşır; gateway açıklamasız gövdeyi platforma göndermez.
+
+```jsonc
+{ "name": "anket-kaydet", "slug": "anket-kaydet", "source": "workflow",
+  "description": "Anket başlığı ve sorularını tek çağrıda kaydeder; oluşan anketin id'sini döner." }
+```
+
+**Çağıranın ne elde ettiğini yaz**, kaynağın şeklini değil: `"workflow kaynaklı POST ucu"`
+gövdeden zaten okunuyor. Alan kalıcıdır, çalışma zamanını etkilemez, Studio'da servis formunda
+görünür ve elle düzeltilebilir. Adım düzeyindeki karşılığı `platform_guide('workflow')` §WF-024.
+
+## Tuzağı varsa `caution` yaz (opsiyonel, kural yok)
+
+`description` ucun ne işe yaradığını söyler; `caution` **çağıranın bilmezse yanılacağı şeyi**
+söyler. Hiçbir kural zorlamaz — ucun gerçek bir tuzağı yoksa alanı hiç yazma.
+
+- **Anonim uç** — "bu uç auth istemiyor; kimlik kapsaması yalnız bağlı middleware'de yapılır"
+- **Sayfalama yok** — "limit uygulanmaz, tablo büyüdükçe yanıt büyür"
+- **Atomik değil** — "çok adımlı yazım middleware'siz atomik değil; yarıda kalırsa kısmi yazar"
+- **Sessiz boş dönüş** — "filtre eşleşmezse 404 değil boş dizi döner"
+
+```jsonc
+{ "name": "urun-listesi", "httpMethod": "Get",
+  "description": "Aktif ürünleri ada göre sıralı döner.",
+  "caution": "Sayfalama yok; katalog büyüdükçe yanıt boyutu doğrusal büyür." }
+```
+
+Doldurma metin yazma: `"bu uç veri döner, dikkat"` hiçbir şey eklemez. Alan inerttir, Studio'da
+servis formunda görünür ve `microservice_get` outline görünümünde geri okunur.
+
 ## Karar kuralları
 
 1. **Kaynak seçimi sırası: `table` → `view` → `workflow` → `query`.**
@@ -297,6 +330,8 @@ kabul etti. Ayrıntı ve doğru rol kapısı tarifi: `platform_guide('middleware
 
 ## Sık hatalar
 
+- `description` boş (MS-014, block — uç listesinde ne işe yaradığı okunamaz)
+
 - `selectFields: []` + join → tüm alanlar + katlanmış maliyet (MS-001, block)
 - `operation: 'list'` → geçersiz; `get` + `isSingle: false` kullanın (PLT-006)
 - Üst seviye `entityId` eksik (MS-004, warn)

package/dist/resources/guides/middleware.md

@@ -13,6 +13,12 @@ kavramı olmayan bir üründe auth middleware'i, ayar tablosu olmayan bir ürün
 kur** — giriş sayfası + korunacak her uç ve her sayfa `middlewareIds`'e bağlı. Kısmi koruma,
 sistemi güvenli gösterip açık bırakır.
 
+## Açıklama zorunlu
+
+Middleware de bir workflow'dur: her adımı ve middleware'in kendisi `description` taşımak
+zorundadır (**WF-024**, block). Guard'larda bu özellikle önemli — "neden reddediyor" sorusunun
+cevabı adımın ifadesinde gizlidir. Ayrıntı ve yazım ölçütü: `platform_guide('workflow')` §WF-024.
+
 ## Çalışma modeli — bunları bilmeden middleware yazma
 
 1. **Sıra ada bağlıdır.** Bağlı middleware'ler **ada göre alfabetik** koşar — uç yolunda
@@ -54,6 +60,10 @@ sistemi güvenli gösterip açık bırakır.
 6. Middleware transaction içinde koşar: hedef başarısız olursa middleware'in yazdıkları da
    geri alınır (microservice yolu).
 
+> Gateway middleware tanımına da hata yolunu otomatik ekler (start adımına `global-error` dalı +
+> 500 dönen `gatewayOnError` response adımı). Guard middleware'i patladığında ham exception
+> yerine denetimli bir gövde döner. Ayrıntı: `platform_guide('workflow')` → "Hata yolu".
+
 ## Yalnız middleware'de geçerli step'ler
 
 | Step | Ne yapar | Kritik alanlar |

package/dist/resources/guides/page.md

@@ -155,10 +155,13 @@ olaylarında **boştur** (ölçüm 2026-08-25, kaynak okuması: `flow-machine.ts
 
 Pratik kural: **`payload` anahtarları aynı zamanda prop adlarıdır; akışta `self.<anahtar>` ile
 oku** (ya da `value { type:'property', ref:{ source:'component', element, property } }` ile).
-`event.data` yalnız `params` ile gelen olaylarda dolar — pratikte `html` komponentinin
-`fireEvent` aksiyonları (`platform_guide('html')`). Sessiz hata örneği: sayfalama akışını
-`event.data.limit`'e bağlarsan sorgu `LIMIT null OFFSET null` ile koşar ve **tüm satırları**
-döndürür; hata yok, sayfalama yok.
+`event.data` yalnız `params` ile gelen olaylarda dolar — `html` komponentinin `fireEvent`
+aksiyonları (`platform_guide('html')`) ve **2026-08-27 kuşağı komponentler** (`eventcalendar` ·
+`importwizard` · `kanban` · `signature` · `stepper`): bu kuşak `params`'ı da gönderir, yani
+yükleri `event.data.<anahtar>` ile okunur; `kanban` ve `eventcalendar` yükü `self`'e HİÇ
+yazmaz (`component_get` çıktısındaki sözleşme notları ayrımı söyler). Sessiz hata örneği:
+sayfalama akışını `event.data.limit`'e bağlarsan sorgu `LIMIT null OFFSET null` ile koşar ve
+**tüm satırları** döndürür; hata yok, sayfalama yok.
 
 | Komponent · olay | Yük (aynı zamanda prop adları) | Akışta nereden okunur |
 |---|---|---|
@@ -175,7 +178,12 @@ döndürür; hata yok, sayfalama yok.
 | `tabs.tab` | `{ selected }` | `self.selected` |
 | `chart.dataPointClick` | `{ name, seriesName, value, dataIndex, row }` | `self.row` (kaynak satırın tamamı) |
 | `repeater.change` | `{ selectedIndex }` | `item` / `Row` satır bağlamı |
-| `html` aksiyonu (`fireEvent`) | ikinci argüman | **`event.data`** (tek istisna) |
+| `html` aksiyonu (`fireEvent`) | ikinci argüman | **`event.data`** |
+| `kanban.cardMove` | `{ id, row, from, to }` | **`event.data`** (self'e yazılmaz) |
+| `eventcalendar.eventMove` | `{ id, row, start, end, previousStart, previousEnd }` | **`event.data`** (self'e yazılmaz) |
+| `importwizard.complete` | `{ rows, errors, fileName, total }` | `self.rows`… ya da `event.data` |
+| `stepper.stepChange` | `{ currentStep, previous }` | `self.currentStep` ya da `event.data` |
+| `signature.change` | `{ value }` | `self.value` ya da `event.data.value` |
 
 Adım gövdesi `StepManagementSchema`: `{ stepId, name, type, kind, args, branches }`.
 **`branches[].nextStepId` bir GUID değil, hedef adımın `stepId` STRING'idir**
@@ -462,8 +470,8 @@ gateway **PAGE-011 / LAY-004** ile istek gitmeden reddeder.
 
 | slug | Olaylar | Ayırt edici prop'lar |
 |---|---|---|
-| `table` | 8: `mount · pagination · filter · sort · select · selectionChange · doubleClick · rowChange` | `rowSelection` (none/single/multi), `selectedRow`/`selectedRows`, `filterMode` (panel/hide/row), `filters`, `showSort`, `sortField`/`sortType`, `isEditable`, `showColumnMenu`, `actions`, `emptyIcon/emptyText/emptyActions`, `style` (root/thead/th/tr/td) |
-| `datatable` | 1: `mount` | `title`, `locale` (tr/en), `tableStyle` (zebra/plain), kolonlarda `isFilterable`/`isSortable`/`colorMap`/`prefix`/`suffix`/`precision`/`thousands`/`dateFormat`/`imageShape`, `filters`/`sortField`/`sortType` (hidden), `actions` |
+| `table` | 8: `mount · pagination · filter · sort · select · selectionChange · doubleClick · rowChange` | `rowSelection` (none/single/multi), `selectedRow`/`selectedRows`, `filterMode` (panel/hide/row), `filters`, `showSort`, `sortField`/`sortType`, `isEditable`, `showColumnMenu`, `actions`, `emptyIcon/emptyText/emptyActions`, `style` (root/thead/th/tr/td), satır bazlı `_columns`/`_actions` ezmesi (Kural 1e-2) |
+| `datatable` | 1: `mount` | `title`, `locale` (tr/en), `tableStyle` (zebra/plain — satır zemini varyantı), **`style`** (parça bazlı CSS: `&__toolbar`/`&__title`/`&__head`/`&__th`/`&__body`/`&__row`/`&__td`), kolonlarda `isFilterable`/`isSortable`/`colorMap` (statik)/`prefix`/`suffix`/`precision`/`thousands`/`dateFormat`/`imageShape`/**`progress`** kolon tipi, `filters`/`sortField`/`sortType` (hidden), `actions` |
 
 **`datatable`'ın tek olay yayması eksiklik değil, tasarım.** Filtre paneli, sıralama ve sayfalama
 komponentin İÇİNDE: kullanıcı süzdüğünde/sıraladığında/sayfa değiştirdiğinde `datatable` önce
@@ -487,8 +495,18 @@ olarak gider ve ancak `enableDynamicFilters: true` olan bir uçta karşılık bu
   düzenleme (`isEditable`) ve boş-durum aksiyonları verir.
 - *Satır seçimi / çift tıkla forma geçiş / hücre düzenleme gerekiyor mu?* → **`table`**; bunlar
   `datatable`'da yok.
-- *Zengin kolon biçimlendirme (renk haritası, para birimi öneki, tarih formatı, avatar) gerekiyor
-  mu?* → **`datatable`**; kolon şeması bunun için tasarlandı.
+- *Sayı/tarih/görsel biçimlendirme (para birimi öneki, ondalık, binlik ayracı, tarih formatı,
+  avatar şekli) gerekiyor mu?* → **`datatable`**; `prefix`/`suffix`/`precision`/`thousands`/
+  `dateFormat`/`imageShape` yalnız onun kolon şemasındadır, `table`'da yoktur.
+- *Renk gerekiyor mu?* → **ikisi de yapar ama farklı şeyi.** `datatable`'ın `colorMap`'i
+  **statiktir**: hücrenin kendi değerine bakar; satır verisinde rengi taşırsan (`{ label, color }`)
+  dinamik de olur. `table` ise satır bazında **koşullu** renklendirir (`_columns` ezmesi,
+  Kural 1e-2). İkisinin de `style` prop'u vardır (datatable'ınki 2026-08-27'de eklendi), yani
+  renk uğruna stilden vazgeçmen gerekmiyor.
+- *Hücrenin içinde ilerleme çubuğu ya da yüzde halkası mı istiyorsun?* → **`datatable`**, kolon
+  tipi `progress`. `progressVariant` çubuk/halka, `thresholds` yüzdeye göre renk, `captionField`
+  ise BAŞKA bir satır alanını çubuğun üstüne yazar — ad ve çubuk tek hücrede durur. `table`'da
+  böyle bir kolon tipi yok.
 
 **Bu, katalogdaki her komponent için geçerlidir:** hangi komponenti kullanacağını
 `component_list`/`component_get` ile keşfedip kendin seçersin, rehberdeki örnekler tercih değil
@@ -504,6 +522,48 @@ görünür, kullanıcı süzer, hiçbir şey olmaz. Ya süzme arayüzünü kapat
 > eklersen elementId aynı olsa bile o bağ kopar ve flow'u yeniden kaydetmen gerekir. Tipi
 > baştan doğru seç.
 
+## Kural 1e-2 — Satır bazlı renk `table`'da: `_columns` ezmesi
+
+`table` her hücreyi çizerken **satırın kendi `_columns` sözlüğünü** kolon tanımıyla birleştirir
+(`column-view.ts` `resolveColumn` → `Table.svelte:1207` `<TableCell {column}>`). Yani bir satır
+kendi `appearance`/`isBold`'unu dayatabilir; renk, satırın herhangi bir alanından hesaplanır:
+
+```jsonc
+// setter: rows'a yazmadan önce satırları zenginleştir
+{ "type": "change", "element": "tbl", "property": "rows", "source": "component",
+  "mapping": { "source": "", "mappings": {} },
+  "value": { "type": "code", "ref": "(Steps.listele?.data || []).map(function (r) { return Object.assign({}, r, { _columns: [null, null, null, null, { appearance: r.durum === 'İptal' ? 'error' : 'success' }] }); })" } }
+```
+
+**`_columns` bir DİZİDİR ve konum kolonun `columns` dizisindeki İNDEKSİDİR** — yukarıdaki dört
+`null`, hedef kolon 5. sırada (indeks 4) olduğu için var; ezilmeyen kolonlar atlanır.
+`buildViewColumns` `index`'i `isHidden` kolonlar elenmeden ÖNCE atar, yani **görünür sıra değil
+tanım sırası**: gizli bir `id` kolonu indeksleri kaydırmaz, kullanıcının kolon menüsünden kolon
+gizlemesi de kaydırmaz (`hideColumns` `buildViewColumns`'dan SONRA uygulanır).
+Aynı kalıp `_actions[i]` ile satır bazlı **aksiyon** ezmesinde de çalışır (tek bir satırda "Sil"i
+`{ "isHidden": true }` ile gizlemek gibi).
+
+> Sözleşme frontend'de belgeli ve testli: `column-view.ts` `resolveColumn` + `column-view.spec.ts`
+> (`applies the row's own override fields on top`, `matches the override by the column definition
+> order`). Ezilebilen alanlar `appearance` · `options` · `isBold`. CSV export'u da bu ezmeyi
+> uygular, yani ekranda gördüğün renk dışa aktarımda da tutarlıdır.
+
+İki renk yolu var:
+
+| istenen | yol |
+|---|---|
+| Hazır palet | `tag` kolonu + `appearance`: `primary · info · success · warning · error`; `_columns` ile satır satır değişir |
+| Serbest hex | `tags` kolonu + satır verisinde `[{ "value": "kritik", "color": "#da1e28" }]` |
+
+**`style` yazarken iki ayrı kural geçerli:** `style.root` emotion'dır (camelCase çalışır, iç
+seçici yazılabilir); `style.thead|th|tr|td` ise satır içi `style` attribute'una basılır
+(`toStyleString` anahtarı olduğu gibi yazar) — bu dördünde **kebab-case zorunludur**, `fontSize`
+sessizce düşer, `font-size` çalışır.
+
+> `datatable`'da `style` prop'u **yoktur** (ne şemada ne `.svelte`'de) ve `_columns` ezmesi de
+> yoktur; `tableStyle` CSS değil `zebra`/`plain` varyantıdır. Tabloya CSS ya da koşullu satır
+> rengi gerekiyorsa **`table`**.
+
 ## Kural 1f — Koordinat modeli ve layout-slot yerleşimi
 
 Izgara kapsayıcıya görelidir ve **bir satır ≈ 10px**'tir; `w` 12 kolon. Her komponentin
@@ -616,7 +676,11 @@ Dört şeyi bilmeden flex kurma:
 3. **Flex kapsayıcının yüksekliği içeriğine oturur.** `verticalAlign`'ın dağıtacak boşluğu
    olması için `appearance.heightType: 'fixed'` + `size.h` vermelisin. **İstisna
    `page_container`**: `states.isWrapper: true` olduğu için zaten `min-height: 80vh` alır
-   (Kural 1f), dolayısıyla dikey hizalama onda kutu boyu vermeden de çalışır.
+   (Kural 1f), dolayısıyla dikey hizalama onda kutu boyu vermeden de çalışır. Üçüncü yol
+   `heightType: 'fill'` (2026-08-28): çocuk kabın bıraktığı yeri alır — sütunda `flex: 1 1 auto`,
+   satırda `align-self: stretch` — yani "şu kutu kalan alanı kaplasın" artık tahmini bir `h`
+   olmadan yazılabilir. Tam ekran kabuk kurmanın yolu da budur: `platform_guide('layout')`
+   Kural 5b.
 4. **`layout: 'grid'` iken diğer altı prop ÖLÜDÜR.** Katalogda tanımlı oldukları için
    doğrulama duvarı susar, renderer da okumaz: ızgara kapsayıcıya `direction: 'column'` yazmak
    sessizce hiçbir şey yapmaz. Gateway bunu **PAGE-015 (uyarı)** ile söyler.
@@ -799,11 +863,11 @@ yapmazsan ekran "platform mavisi" görünür; marka rengine çevirmek tek satır
 | Küme | Değişkenler |
 |---|---|
 | Vurgu | `--ng-accent-primary` · `--ng-accent-hover` · `--ng-accent-muted` · `--ng-accent-subtle` |
-| Zemin | `--ng-background-canvas` · `--ng-background-surface` · `--ng-background-surface-alt` · `--ng-background-readonly` · `--ng-background-disabled` · `--ng-background-overlay` |
+| Zemin | `--ng-background-canvas` · `--ng-background-surface` · `--ng-background-surface-alt` · `--ng-background-readonly` · `--ng-background-disabled` · `--ng-background-overlay` · `--ng-background-inverse` (zıt zemin: aydınlıkta koyu, karanlıkta açık) |
 | Metin | `--ng-text-primary` · `--ng-text-secondary` · `--ng-text-disabled` |
-| Çerçeve / köşe / gölge | `--ng-border-primary` · `--ng-border-secondary` · `--ng-rounded` · `--ng-shadow-none/sm/md/lg` |
+| Çerçeve / köşe / gölge | `--ng-border-primary` · `--ng-border-secondary` · `--ng-rounded` (= `--ng-radius-md`) · `--ng-radius-sm/lg/pill` (temanın köşe kademeleri; sm/lg `--ng-rounded`'ın oranı) · `--ng-shadow-none/sm/md/lg` |
 | Tipografi | `--ng-font` · `--ng-font-size` · `--ng-font-weight` |
-| Boşluk | `--ng-spacing` · `--ng-spacing-small` · `--ng-spacing-large` |
+| Boşluk | `--ng-spacing` · `--ng-spacing-xs/sm/md/lg/xl` (kademeler; builder'ın gap preset'leri sm/md/lg'yi okur — custom properties'te de bunları kullan) · `--ng-spacing-small` · `--ng-spacing-large` (eski adlar) |
 | Durum | `--ng-status-success` · `--ng-status-warning` · `--ng-status-error` · `--ng-status-info` |
 | Form (girdilerin tamamı) | `--ng-form-color` / `-disabled` / `-placeholder` / `-invalid` · `--ng-form-background` / `-disabled` / `-readonly` · `--ng-form-border` / `-focus` / `-disabled` / `-invalid` · `--ng-form-radius-sm/md/lg` · `--ng-form-height-sm/md/lg` · `--ng-form-padding-x-sm/md/lg` · `--ng-form-font-family` · `--ng-form-font-size-sm/md/lg` · `--ng-form-label-color` / `-font-weight` / `-font-size-*` / `-margin-bottom-*` · `--ng-form-default-size` |
 
@@ -879,6 +943,47 @@ kaplar — yardım metni opsiyonelse bunu hesaba kat.
 > `input` `display:none` olduğu için klavye odağı görünmez. Klavyeyle gezilecek ekranlarda
 > `&__item-input:focus-visible + &__item-text` için de bir dış çizgi tanımlayın.
 
+### 1h-4 — Stilin ÜÇ kanalı ve efektif sonucu okuma
+
+`style` tek kanal değildir; bir düğümün ekranda aldığı görünüm üç ayrı yerden gelir ve hangisini
+kullanacağını bilmek gereksiz CSS yazmayı önler:
+
+| Kanal | Ne için | Nereden yazılır |
+|---|---|---|
+| `appearance` (düğüm alanı) | dış/iç boşluk, genişlik-yükseklik, z-index, opaklık, taşma, **sarmalayıcının** zemini/çerçevesi/gölgesi | `page_schema_patch` ile düğümün `appearance` alanı |
+| Şema prop'ları | yerleşim (`layout`/`direction`/`gap`/`gridColumns`), semantik renkler, boyut (`size`) | `replace_prop` |
+| `style` prop'u | geri kalan her şey; iç seçiciler, pseudo-class, `--ng-*` token ezme | `replace_prop` / `set_binding` |
+
+**Dikkat — `appearance` kutunun İÇİNİ boyamaz.** Yüzey stili düğüm sarmalayıcısına
+(`.ng-app__node-item`) yazılır; `box` gibi kendi zeminini çizen bir komponentin içi bundan
+etkilenmez. Tipli stil modeline göçen komponentler bu boşluğu kapatır: `box` (ve emekli
+takma adı `aibox`: `surfaceStyle` · `typographyStyle` · `hoverStyle` · `sectionStyle`),
+`container` (aynı üçlü + `headerStyle`), `text` (`typographyStyle` · `surfaceStyle`;
+hover/bölge yok), `statcard` (üçlü + `valueStyle`) ve `icon` (yalnız `hoverStyle`;
+yüzey/tipografi kararları çip ve boyut prop'larında) — `component_get('<slug>')` sözleşmeyi
+verir, göçen komponentlerin listesi `TYPED_STYLE_COMPONENTS` kaydıdır.
+
+**Stil yazma SIRASI (tipli gruplu komponentlerde):** önce tipli gruplar — kararın alanı
+grupta varsa ORAYA yaz; grubun karşılamadığı her CSS kararı `style` kanalına (studio'daki
+"custom properties" alanının veri kanalı budur). Tipli alan dururken aynı özelliği `style`'a
+yazma: `style` kazanır ama panel alanı etkisiz görünür ve tasarımcı yanılır.
+Bileşenin BİLDİRDİĞİ parçalara (`&__header`, `&__body` …) da yazabilirsin: `style: { '&__header':
+{ minHeight: '0' } }` — studio'daki "custom properties" bölümünün Hedef seçicisi bunun panel
+yüzüdür. Boyut alanlarında METİN `'0'` gerçek seçimdir (bileşenin taban dolgusunu/yüksekliğini
+kaldırır); sayı `0` "seçilmedi" sayılır.
+**Katman sırası (K4):** tema `componentStyles` → `$preset` TABANDIR (varsayılan verir);
+tipli grup alanları temayı alan alan EZER; düğümün serbest `style`'ı en üstte SON SÖZDÜR.
+Boyut alanları CSS uzunluğu metnidir (`'18px'`, `'1.2em'`); `radius` tek alanda preset
+anahtarı YA DA CSS uzunluğu kabul eder.
+**Tema preset'i bağlamak:** `style: { $preset: 'card' }` (adlar `project_get` → `theme.presets`;
+`componentStyles[type]` referanssız uygulanır). Bir alanı temaya bırakmak = o alanı hiç yazmamak;
+studio'da bunun adı "Temaya dön"dür. Tema değerini gruba kopyalama — bağ kopar, tema değişince izlemez.
+
+**Efektif stili okumak:** `page_runtime_get(resolveStyles: true)` her düğüme `resolvedStyle`
+(kaskad çözülmüş birleşik stil) ve `styleLayers` (`{ typedGroups, componentStyle, preset, own }`)
+ekler. "Bu kutu neden böyle görünüyor / benim yazdığım stil neden görünmüyor" sorusunun cevabı
+budur — bir preset ya da `componentStyles` sizin değerinizi eziyorsa `styleLayers` söyler.
+
 ## Kural 2 — Şema değişikliği `page_update` ile YAPILMAZ
 
 İki ayrı yazma yolu vardır ve karıştırılmaz:
@@ -1337,6 +1442,10 @@ bağlanır, filtre `source:'expression'` + `value:'user.id'` olur.
 | Kimlik alanları | `email` · `password` |
 | Dosya | `fileUpload` (dropzone) · `fileInput` · `filebutton` · `file-viewer` |
 | Liste | `table` · `datatable` (Kural 1e) · `repeater` (kart listesi VE dinamik form — Kural 1g) · `tree-view` (hiyerarşi; `isSearchable` ile istemci içi arama) · `timeline` (tarihli olay akışı) |
+| Pano / takvim | `kanban` (durum kolonlarında sürüklenebilir kartlar; taşıma `cardMove` ile `event.data`'dan okunur, kalıcılık AKIŞIN işidir) · `eventcalendar` (ay/hafta/gün; veri `rows`'a akışla yazılır, `monthChange` tazeleme kancasıdır, `month` 1-tabanlı) |
+| Kayıt detayı | `detailview` — tek kaydı etiket/değer ızgarası basar (alan başına format, iç içe alan yolu); OLAY YAYMAZ, tıklanabilirlik gerekiyorsa kapsayıcıya sar |
+| Adımlı akış | `stepper` — tabs gibi her adım kendi droppable görünümünü taşır; ileri gidiş `canProceed` kapısıyla (`{{ form1.isValid === true }}` biçimi), adım `currentStep` setter'ıyla sürülür |
+| İmza / CSV içe aktarma | `signature` (değer PNG data-URL ya da ham SVG; `change` setter'lı) · `importwizard` (3 adımlı sihirbaz; temiz+hatalı satırlar `complete` yükünde — satırları uca yazmak akışın işidir) |
 | Sayfalama (tablo dışı listeler için) | `pagination` — offset/limit yazar, `self.offset`/`self.limit` ile sorguya bağlanır |
 | Grafik / KPI | `chart` (ECharts: bar·line·area·pie·donut + waterfall/histogram/pareto/bullet/tornado/radial) · `statcard` (tek KPI + trend + sparkline) · `progress` |
 | Kapsayıcı / düzen | `container` (ızgara ya da flex — Kural 1f-2) · `form` (düzen prop'u YOK, çocuklar ızgara koordinatıyla dizilir) · `tabs` · `collapsible-container` · `accordion` |
@@ -1344,7 +1453,7 @@ bağlanır, filtre `source:'expression'` + `value:'user.id'` olur.
 | Katman | `modal` · `drawer` (şema kökünde — Kural 1d) |
 | Geri bildirim | `notification` (sayfa içi kutu) · `toast` (geçici bildirim; isOpen yükselen kenarı) · `form-validation-errors` · `confirm-bar` · `result` (işlem sonucu ekranı) · `emptystate` (boş liste; ikon YA DA görsel + aksiyon düğmeleri) |
 | Gezinme / başlık | `breadcrumb` · `breadcrumb-title` (başlık + daralan iz) · `page-header` · `header` · `sidebar` · `auth-layout` · `language-selector` (dil değiştirici — çoklu dil kurulumu `platform_guide('translation')`) |
-| Sunum | `text` · `html` · `image` · `video` · `icon` · `qrcode` · `tags` · `avatar` · `badge` (sayaç “99+” / nokta / durum metni) · `carousel` · `iframe` (sandbox’lı gömme) · `jsonviewer` (katlanabilir JSON; JSON METNİNİ de parse eder) · `audit-basic` · `audit-history` |
+| Sunum | `text` · `html` · `image` · `video` · `icon` (Material/Phosphor glif; çip + rozet + spin + click/href) · `qrcode` · `tags` · `avatar` · `badge` (sayaç “99+” / nokta / durum metni) · `carousel` · `iframe` (sandbox’lı gömme) · `jsonviewer` (katlanabilir JSON; JSON METNİNİ de parse eder) · `audit-basic` · `audit-history` |
 
 > **`chart` komponenti VAR (2026-08-25 ölçümü) — bu satır düzeltildi.** Rehberin önceki hâli
 > "grafik komponenti yoktur, `html` + `loadScript` kullanın" diyordu; `component_list` çıktısında
@@ -1515,6 +1624,15 @@ micro-op hattına dönün.
   style + Kural 1h deseniyle yeniden kurulunca kart 400px'e ve ortaya oturdu. Gateway bunu **PAGE-014 (uyarı)** ile
   yanıtın `layoutWarnings` alanında bildirir. **Düzeni `style` ile kurmaya hiç kalkışma:**
   ortalama/yaslama/aralık işi kapsayıcının kendi `layout: 'flex'` prop grubuna aittir (Kural 1f-2).
+- **Menüde "bulunduğun sayfa" vurgusu: `sidebar`/`layout`'ta `activeHref`, `header`'da
+  `activeNavHref`.** `sidebar` ve `layout` menü ağacını ortak renderer'la çizer: `activeHref` boşken
+  tarayıcıdaki adrese uyan satırı kendileri vurgular, prop yazılırsa o satır vurgulanır (akıştan
+  setter ile de yazılabilir). Eşleşmenin iki tarafı da `getHref`'ten geçtiği için satırın ham
+  `href`'ini, bağlantı seçicisinin nesnesini ya da tam yolu yazmak aynı satırı gösterir. `header`
+  yalnız prop'a bakar (adrese bakmaz), `qm-header` ise yalnız adrese bakar (prop'u yoktur). Menü
+  satırları `style`'ın `&__navigations*` parçalarıyla biçimlendirilemez ve menü olay yaymaz —
+  vurgu dışında bir "seçili satır" davranışı kurulamaz. Ayrıntı:
+  `component_get('sidebar' | 'layout' | 'header' | 'qm-header')`.
 - **`isHidden` olmayan komponent listesine `dropdown` da dahildir** (`text`, `multi-select`,
   `dropdown`). Koşullu göstermek için `isHidden`'ı olan bir `container`'a sar (Kural 1g).
 - **Ana sayfayı TAŞIYAMAZSIN — `application_update.homepageId` kalıcı DEĞİL ve yanıtı yanıltıcı.**

package/dist/resources/guides/workflow.md

@@ -2,6 +2,65 @@
 
 Buradaki kurallar gerçek projelerde (qm, hr) **deneyerek doğrulandı**.
 
+## Her adım NE İŞE YARADIĞINI yazar (WF-024, block)
+
+Studio kanvası adımın **adını** gösterir, ne yaptığını göstermez. 11 satırlık bir `code` adımının
+işini anlamak için ifadeyi satır satır okumak gerekir — akışı devralan geliştirici için bu, her
+seferinde tersine mühendisliktir. Bu yüzden **her adım** ve **akışın kendisi** bir `description`
+taşır; gateway açıklamasız gövdeyi platforma göndermez.
+
+```jsonc
+{ "name": "anket-kaydet", "type": "workflow",
+  "description": "Anket başlığını ve sorularını tek çağrıda kaydeder.",
+  "steps": [
+    { "id": "<GUID>", "name": "createSurvey", "type": "table",
+      "description": "Anket başlığını surveys'e yazar; oluşan id sonraki adımlarda kullanılır.",
+      "rule": { … } }
+  ] }
+```
+
+- **Mekanizmayı değil NİYETİ yaz.** `"assignments tablosunu status='Aktif' ile okur"` koddan zaten
+  okunuyor ve hiçbir şey eklemiyor. `"kullanıcının asal pozisyonunu seçer; birden çok aktif atama
+  varsa is_primary olanı tercih eder, o da yoksa ilkini alır"` — yazılmadıkça hiçbir yerde
+  bulunmayan bilgi budur.
+- **`start` ve `end` muaftır** (kural onları hiç sormaz): ikisi de yapısal işaretçi, açıklanacak
+  davranışları yok.
+- **Gateway'in enjekte ettiği `gatewayOnError` adımı kendi açıklamasını taşır** — o adımı sen
+  yazmadığın için kural seni onun yüzünden durdurmaz.
+- Alan **kalıcıdır ve çalışma zamanını etkilemez**: motor okumaz, yalnız Studio'da kanvas
+  düğümünde ⓘ ikonu + popover olarak ve adım panelinde düzenlenebilir metin olarak görünür.
+  İnsan da düzeltebilir.
+- `preview` bu kuralın dışındadır — kaydedilmeyen bir denemede açıklama aranmaz.
+- Aynı disiplin ucun kendisi için de geçerli: `platform_guide('microservice')` §MS-014.
+
+## Tuzağı varsa `caution` yaz (opsiyonel, kural yok)
+
+`description` "bu adım ne işe yarar" sorusunu cevaplar. `caution` bambaşka bir soruyu cevaplar:
+**"burada neye dikkat etmek gerekiyor."** İkisi ayrı alandır çünkü tek metne sıkıştırıldıklarında
+ikisi de okunmaz olur — açıklama uyarı listesine döner, uyarı da açıklamanın içinde kaybolur.
+
+**Bu alanı hiçbir kural zorlamaz ve doldurma metin kabul edilmez.** Adımın gerçek bir tuzağı
+yoksa alanı hiç yazma. Yazmaya değer olanlar:
+
+- **İdempotent değil** — "iki kez çalışırsa çift atama yazar; çağıran tarafta koruma yok"
+- **Kapsam bu adımda değil** — "tenant filtresi burada yok, kimlik kapsaması bağlı middleware'de"
+- **Dış bağımlılık** — "ödeme sağlayıcısına senkron çağrı; sağlayıcı yavaşlarsa istek bekler"
+- **Sessiz düşen dal** — "eşleşme bulunamazsa hata dönmez, boş dizi döner"
+
+```jsonc
+{ "id": "<GUID>", "name": "createAssignment", "type": "table",
+  "description": "Kullanıcıyı seçilen pozisyona atar.",
+  "caution": "İki kez çalışırsa çift atama yazar; çağıran tarafta idempotency koruması yok." }
+```
+
+**Yazılmayacaklar:** `"bu adım veriyi okur, dikkat"` gibi mekanizma tekrarı, `description`'ın
+başka kelimelerle yazılmışı, `"dikkatli olun"` gibi genel tavsiye. Bunlar kanvastaki ⚠ işaretini
+değersizleştirir — işaretin tüm değeri **seyrek** olmasından gelir.
+
+Alan `description` gibi inerttir: motor okumaz. Studio'da kanvas düğümünde kehribar ⚠ ikonu,
+adım panelinde düzenlenebilir metin, analiz belgesinde ayrı satır olarak görünür; `workflow_get`
+outline görünümünde geri okunur — sonraki oturumda tuzağı tam gövdeyi almadan görürsün.
+
 ## Karar kuralları
 
 1. **DTO önce (yalnız workflow tipinde).** `type='workflow'` için girdi/çıktı sözleşmesini
@@ -49,6 +108,55 @@ Bağlanmamış step çalışmaz. `start` tek branch taşır; normal step'ler `su
 `condition` koşul branch'leri + `else`; terminal step'ler (`response`, `convert`, `revert`,
 `end`) **branch taşımaz**.
 
+## Hata yolu
+
+**Gateway workflow ve middleware tanımlarına hata yolunu otomatik ekler** (yanıtta
+`gatewayNormalized`): start adımına `type: 'global-error'` dalı + 500 dönen bir `response` adımı
+(`gatewayOnError`). Kendi hata gövdeni istiyorsan bu adımın `bodyExpression`'ını değiştir ya da
+tanımı kendi global-error dalınla gönder — dal **bağlıysa** (`nextStepId` doluysa) gateway
+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.
+
+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": [ … ] } }
+```
+
+`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.
+
+**Kurallar ve sınırlar:**
+
+- **Global-error dalı TEK olmalı ve START adımında durmalı.** Başka adıma koyulan dal hiç
+  çalışmaz, platform 400 döner. Gateway bunu `WF-022` ile istek gitmeden reddeder.
+- **Hata `response` adımı ReturnDto'ya bağlı değildir.** Global-error modunda platform sözleşmeyi
+  atlar, gövde serbesttir — `returnDtoId` ile çakışmaz.
+- **Loop içi hatalar global-error dalına GİTMEZ.** Loop çocuk bağlamı bu yönlendirmeyi kapatır;
+  loop adımının kendi `fail` dalını bağla.
+- **`automation` tipinde `response` adımı yasaktır**, bu yüzden gateway bu tipe enjeksiyon
+  yapmaz. Hata yolunu kendin yaz: global-error dalını `revert` (tetikleyen satır işlemini geri
+  alır) ya da `email`/`table` adımına bağla. Bağlı hata yolu yoksa `WF-021` uyarır.
+- **Hata yolu hiç yoksa** akış patladığında platform 500 + ham exception mesajı döner. Çalışır,
+  ama çıktı denetimsizdir ve lokalize değildir.
+
+> **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
+> `children` ve tetiklenen `automations` dâhil) tarar ve hata bulursa yanıta `runtimeErrors`
+> alanını ekler — `workflow_preview` ve `automation_preview` yanıtlarında bu alanı kontrol et.
+>
+> **`runtimeErrors` her tool'da aynı şeyi ölçmez.** Alan yalnız `steps[]` taşıyan yanıtlarda adım
+> adım tarama yapar. `microservice_execute` / `microservice_debug` / `microservice_preview`
+> yanıtlarında gateway sadece `httpStatus >= 400` durumunu bulgu sayar: bu tool'lar adım ağacını
+> `executionItems` olarak döner ve o düğümlerde hata işareti yoktur, yani HTTP 200 gövdesine gömülü
+> bir microservice hatası `runtimeErrors` üretmez. Orada `body`'yi kendin oku ve şüpheliyse
+> `microservice_debug` ile adım adım bak. `query_preview` yanıtları hiç kapsanmaz.
+
 ## Condition step kuralları
 
 Koşullar `rule.items[]` dizisindedir ve **sırayla** değerlendirilir; ilk `true` olan dala
@@ -151,6 +259,11 @@ Tek uçta "başlık + N alt kayıt" yazmanın yolu budur (anket + sorular + seç
 
 - `rule` içinde `datasourceId` + `entityId` zorunlu; `selectFields`/`filters` öğelerinde
   **`fieldId` zorunlu** (yalnız `fieldSlug` yetmez → `EvaluateWorkflowStepFailedException`).
+- **`selectFields` = akışın gerçekten OKUDUĞU alanlar.** Entity'nin tüm alanlarını işaretlemek
+  her satırı gereksiz büyütür (join'li adımda maliyet katlanır) ve adımın ne ürettiğini
+  okunamaz hâle getirir. Sonraki adımların, filtrelerin ve response `bodyExpression`'ının
+  dokunmadığı alanları çıkarın — gateway bunları **WF-023 (warn)** ile adıyla sayar. Çıktıyı
+  bütün olarak geçiriyorsanız (`{ list: rows.data }`) kural susar.
 - **Table step JOIN kurabilir** ve alias/path disiplini microservice'inkiyle **birebir aynıdır**
   (Studio aynı form bileşenlerini kullanır): `joins[].path` = `<kökEntityId>.<ilişkiAlanı…>`,
   join'li `selectFields[].path` = kök id olmadan aynı zincir, kök alanlarda `path` yok.
@@ -243,12 +356,15 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
 ```jsonc
 {
   "name": "Product Lookup", "slug": "product-lookup", "type": "workflow",
+  "description": "Ada göre tek ürün getirir; bulunamazsa hata yoluna düşer.",
   "parameterDtoId": "<girdi DTO id>", "parameterBehavior": "object",
   "returnDtoId": "<çıktı DTO id>", "returnBehavior": "object",
   "steps": [
     { "id": "<GUID-1>", "name": "Start", "type": "start",
-      "branches": [{ "id": "<GUID-2>", "name": "start", "type": "success", "nextStepId": "<GUID-3>" }] },
+      "branches": [{ "id": "<GUID-2>", "name": "start", "type": "success", "nextStepId": "<GUID-3>" },
+                   { "id": "<GUID-7>", "name": "global-error", "type": "global-error", "nextStepId": "<GUID-8>" }] },
     { "id": "<GUID-3>", "name": "load_product", "type": "table",
+      "description": "input.productName ile ürünü okur; tek kayıt bekler.",
       "rule": { "stepType": "table", "datasourceId": "<datasource id>", "entityId": "<entity id>",
                 "operation": "get", "isSingle": true,
                 "selectFields": [{ "alias": "<entity slug>", "fieldId": "<alan id>", "fieldSlug": "name" }],
@@ -258,9 +374,16 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
                 "limit": { "name": "limit", "offset": "offset", "source": "query-string" } },
       "branches": [{ "id": "<GUID-4>", "name": "success", "type": "success", "nextStepId": "<GUID-5>" },
                    { "id": "<GUID-6>", "name": "fail", "type": "fail", "nextStepId": null }] },
+                   //                                   ^ bağlanmamış fail dalı: hata global-error dalına gider
     { "id": "<GUID-5>", "name": "product_response", "type": "response",
+      "description": "Bulunan ürünün adını 200 ile döner.",
       "rule": { "bodyExpression": "{ name: load_product.data.name }", "httpStatusCode": 200,
-                "headerExpression": "{  }" }, "branches": [] }
+                "headerExpression": "{  }" }, "branches": [] },
+    { "id": "<GUID-8>", "name": "onError", "type": "response",
+      "description": "Akış patlarsa hata kodunu ve mesajını 500 ile döner.",
+      "rule": { "stepType": "response", "httpStatusCode": 500,
+                "bodyExpression": "({ code: error.code, message: error.message })" },
+      "branches": [] }
   ]
 }
 ```
@@ -315,6 +438,8 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
 - Automation'da `isQueue`/`operation` eksik ya da returnDtoId verilmiş (WF-010, block)
 - `fields` ∩ `selectFields` çakışması (WF-012, warn) · join'li table'da boş selectFields (WF-007, warn)
 - Join'li table step'inde kök `rule.alias` boş (WF-019, block — Postgres 42601'in sebebi)
+- Akışta hiç okunmayan `selectFields` alanı (WF-023, warn — gereksiz taşınan sütun)
+- Adımda ya da akışta `description` yok (WF-024, block — Studio'da adım okunamaz kalır)
 - İlişki alanının içini okuyan ifade (WF-020, warn — join yoksa alan düz FK'dır)
 - `set-user` adımı olmadan `user` okuyan middleware (MW-003, warn)