@appaflytech/zeyrek-ai-mcp 0.0.1

package/dist/resources/guides/view.md

@@ -0,0 +1,89 @@
+# View Rehberi (tam metin arama)
+
+View, **serbest metin araması** içindir: seçtiğin alanlar bir analizörden geçirilip `slug` adlı
+projeksiyon tablosuna indekslenir. **Raporlama/agregasyon aracı değildir** — özet/sayım için
+`query_create` (raw SQL) + query kaynaklı microservice kullan.
+
+Gövde şemaları: `ngapps://schemas/CreateViewCommand` · `ngapps://schemas/UpdateViewCommand`.
+
+## Kuruluş sırası
+
+```
+1. datasource_list        (datasourceId — create'te zorunlu, update'te alan YOK)
+2. entity_get             (indekslenecek alanların fieldId'leri)
+3. view_create
+4. microservice_create    (source: 'view')  ← tüketim yolu
+5. view_rebuild           (toplu veri değişikliğinden sonra)
+```
+
+## Çalışan gövde
+
+```jsonc
+{
+  "name": "Talep Arama", "slug": "ticket_search",
+  "datasourceId": "<datasource id>", "providerType": "postgres",
+  "analyzer": { "language": "turkish", "tokenizer": "standard",
+                "charFilters": [], "tokenFilters": ["lowercase", "asciifolding"] },
+  "entities": [{ "entityId": "<tickets entity id>", "alias": "tickets" }],
+  "fields": [
+    { "viewEntityAlias": "tickets", "fieldId": "<title field id>",       "alias": "title",  "weight": 2 },
+    { "viewEntityAlias": "tickets", "fieldId": "<description field id>", "alias": "body",   "weight": 1 }
+  ]
+}
+```
+
+- `analyzer` verilmezse platform `ViewAnalyzer.Default()` kullanır — Türkçe içerikte
+  `language: 'turkish'` + `tokenFilters: ['lowercase','asciifolding']` açıkça verilmelidir, yoksa
+  "Talep" ile "talep" ya da "yazilim" ile "yazılım" eşleşmez.
+- `fields[].weight` sıralama ağırlığıdır (`double`): başlık 2, gövde 1 gibi.
+- `fields[].viewEntityAlias`, `entities[].alias` ile birebir eşleşmeli. Eşleşmezse alan **sessizce
+  ilk tabloya** bağlanır (`ViewSourceMapper.Map` → `tablesByAlias.GetValueOrDefault(...) ?? tables.FirstOrDefault()`).
+- `view_get` alanları `viewEntityId` ile döndürür, yazma tarafı `viewEntityAlias` ister; gateway
+  çeviriyi yapar, çeviremezse isteği reddeder.
+
+## Enum sözlüğü (hepsi küçük harf)
+
+| Alan | Değerler |
+|---|---|
+| `providerType` | `postgres` |
+| `analyzer.language` | `simple` · `turkish` · `english` |
+| `analyzer.tokenizer` | `standard` · `whitespace` · `edge-ngram` |
+| `analyzer.charFilters[]` | `html-strip` |
+| `analyzer.tokenFilters[]` | `lowercase` · `stopwords` · `stemmer` · `asciifolding` · `synonym` |
+
+`edge-ngram` "yazarken arama" (typeahead) içindir ve indeksi büyütür; tam kelime araması için
+`standard` yeterlidir.
+
+## Çoklu entity JOIN DEĞİLDİR
+
+`entities` birden çok tablo alır, ama aralarında **ilişki tanımı yoktur** — `ViewSourceMapper.Map`
+yalnız tabloları ve alanları eşler. Her tablo ayrı ayrı indekslenir; eşleşme hangi tablodan
+geldiyse dönen kayıt **o tablonun satırıdır**.
+
+Yani *"talebi yorum içeriğinden bul"* bu yolla kurulamaz: yorumdan eşleşme gelirse elinde yorum
+satırı olur, talep değil.
+
+**Doğru desen — denormalize arama alanı:**
+
+```
+1. tickets'a bir arama alanı ekle (ör. search_blob, TEXT)
+2. ticket_comments üzerinde create/update automation'ı: yorum metnini ilgili talebin
+   search_blob'una ekle (row.ticket_id ile talebi bul, mevcut blob + yeni yorum)
+3. view tek entity (tickets) üzerinde title + description + search_blob alanlarını indeksler
+```
+
+Bu kurulumda yalnız yorumda geçen bir kelime **talebi** döndürür. Automation tarifi:
+`platform_guide('workflow')` §"Automation gerçekleri".
+
+## Tüketim: `source: 'view'` microservice'i
+
+View'i okumanın tek yolu view kaynaklı bir microservice'tir ve o uç **zorunlu `searchText`**
+parametresi ister (+ `limit`/`offset`). Ayrıntı: `platform_guide('microservice')`.
+
+## Bakım
+
+- `view_rebuild` projeksiyonu sıfırdan kurar; toplu satır yüklemesinden ya da alan listesi
+  değişikliğinden sonra çağır.
+- View'in `slug`'ı projeksiyon tablosunun/indekslerinin adıdır — slug değiştirmek onları yeniden
+  adlandırır; elle oluşturulmuş bir tabloyla çakışmasın diye entity slug'larıyla aynı isim uzayında
+  düşün (`platform_guide('entity')` §"Slug seçimi").

package/dist/resources/guides/workflow.md

@@ -0,0 +1,359 @@
+# Workflow Rehberi
+
+Buradaki kurallar gerçek projelerde (qm, hr) **deneyerek doğrulandı**.
+
+## Karar kuralları
+
+1. **DTO önce (yalnız workflow tipinde).** `type='workflow'` için girdi/çıktı sözleşmesini
+   DTO olarak kur: `parameterDtoId` + `parameterBehavior`, `returnDtoId` + `returnBehavior`
+   (DtoId verilen her yerde Behavior da zorunlu). Platform her entity için `isDefault: true`
+   DTO üretir — önce `dto_list` ile ara, çoğu zaman yenisini yazmak gerekmez.
+2. **Veri adımı seçimi: önce table.** Query step yalnız ham SQL şartsa.
+3. **Step/branch id'leri gerçek GUID** olmalı (`"s-start"` gibi id'ler `System.Guid` çevrim
+   hatası verir) ve **veritabanında satır oldukları için global benzersiz** — başka akıştaki
+   GUID'i tekrar kullanmak `RowAlreadyExists` üretir; her akışa taze GUID bloğu ver.
+4. **Kaydetmeden önce `workflow_preview`.** Test girdisi **`previewPayload`** anahtarıyla
+   verilir (`parameters`/`input` çalışmaz, ifadeler `undefined` üretir); değişkenler
+   `previewVariables`.
+   - **`previewPayload` bir STRING olmalı ve tek kanonik biçimi `"({ … })"`'dir.** Alan
+     JavaScript **kaynak metni** bekliyor (`PreviewWorkflowCommand` gövdeyi `jsEngine.Eval` ile
+     çalıştırır) ve **ifadenin sonucu bir NESNE olmak zorundadır**:
+
+     ```jsonc
+     "previewPayload": "({ email: 'a@b.c', password: '1234' })"   // ✔ tek doğru biçim
+     "previewPayload": { "email": "a@b.c" }                        // ✘ 500: Unexpected end of input
+     "previewPayload": "JSON.stringify({ email: 'a@b.c' })"        // ✘ SESSİZ: sonuç string, input {} kalır
+     "previewPayload": "{ email: 'a@b.c' }"                        // ✘ SESSİZ: JS bunu BLOK olarak ayrıştırır
+     ```
+
+     Nesne göndermenin hatası gürültülüdür (`Unexpected end of input (<anonymous>:1:8x)`, sabit
+     sütun numarası, step'lerden bağımsız — step ifadelerini suçlamayın). **Sessiz varyant daha
+     tehlikelidir:** ifade nesne üretmezse preview `input: {}` ile koşar ve suçu adıma atan bir
+     mesaj alırsın (`Please provide the 'members.email' parameter.`) — asıl sorun girdinin hiç
+     bağlanmamış olmasıdır. Yanıttaki `"input"` alanının dolu olduğunu her koşumda kontrol et.
+     Gateway üç hatalı biçimi de **WF-016** ile istek gitmeden reddeder.
+     Automation önizlemesinde aynı biçimle `row`/`previousRow`/`operation`, middleware'de
+     `cookie`/`header`/`queryString`/`body`/`triggerSource` anahtarları verilir.
+   - **Preview YAZMAZ — transaction içinde koşup rollback eder.** Adımlar gerçek id'ler döndürür
+     ama koşum bitince o satırlar tabloda **yoktur** (ölçüm 2026-08-17: `users` + `employees` +
+     `leave_balances` yazan bir akış preview'da uçtan uca geçti, sonra `row_list` üçünde de
+     bulamadı). İki sonucu var: (1) yazma adımlı akışları çekinmeden önizleyebilirsin;
+     (2) **döndürdüğü id'ler kalıcı değildir** — o id ile `row_update` denersen
+     `Sequence contains no elements` alırsın ve hata seni entity'yi suçlamaya iter.
+     Kalıcı satır istiyorsan akışı bağlı ucundan `microservice_execute` ile çağır.
+
+## Step'ler nasıl bağlanır
+
+Her step'in `branches[]` dizisi vardır; `nextStepId` sonraki step'in id'sini gösterir.
+Bağlanmamış step çalışmaz. `start` tek branch taşır; normal step'ler `success` + `fail`;
+`condition` koşul branch'leri + `else`; terminal step'ler (`response`, `convert`, `revert`,
+`end`) **branch taşımaz**.
+
+## Condition step kuralları
+
+Koşullar `rule.items[]` dizisindedir ve **sırayla** değerlendirilir; ilk `true` olan dala
+gidilir, hiçbiri tutmazsa `else` dalı yürür:
+
+```jsonc
+{ "id": "<GUID-C>", "name": "status_check", "type": "condition",
+  "rule": { "stepType": "condition", "queryStepSourceType": "library", "isExpression": false,
+            "items": [
+              { "expression": "load_row.data.length === 0",        "branchId": "<GUID-B1>" },
+              { "expression": "load_row.data[0].status !== 'Onaylandı'", "branchId": "<GUID-B2>" }
+            ] },
+  "branches": [
+    { "id": "<GUID-B1>", "name": "<GUID-B1>", "type": "success", "nextStepId": "<404 step>" },
+    { "id": "<GUID-B2>", "name": "<GUID-B2>", "type": "success", "nextStepId": "<422 step>" },
+    { "id": "<GUID-B3>", "name": "else",      "type": "success", "nextStepId": "<devam step>" }
+  ] }
+```
+
+- Her `items[].branchId` bir branch'in **id'sidir**; runtime bu eşleşmeyle dallanır.
+- **Koşul branch'inin `name`'i, kendi id'sinin GUID string'i OLMALIDIR** (`else` dalı sabit
+  `"else"` kalır). Studio kenarları `branch.name` ↔ `items[].branchId` eşleşmesiyle çizer;
+  `randevu_yok` gibi anlamlı bir ad verilirse akış **runtime'da kusursuz çalışır ama Studio'da
+  koşullar bağlanmamış görünür** — sessiz bozulma, execute testi yakalayamaz. Okunabilir
+  adlandırmayı step adında yap; koşulların anlamı ifadelerinden okunur.
+  **Gateway bunu otomatik düzeltir:** `items[].branchId`'nin gösterdiği branch'in adını id'siyle
+  eşitler ve `gatewayNormalized` ile bildirir; eşleşmeyen bir `branchId` kalırsa WF-014 isteği
+  durdurur (o durumda koşul hiçbir dala bağlı değildir).
+- İfadeler önceki step çıktılarıyla çalışır (`<stepAdı>.data…`); ilişki alanı nesne dönebilir,
+  `x.doctor_id.id ? x.doctor_id.id : x.doctor_id` kalıbı iki biçimi de karşılar.
+
+## Üç workflow tipi
+
+| type | Ne zaman | Tetiklenme | Özel kurallar |
+|---|---|---|---|
+| `workflow` | REST ucu gibi çağrılabilir iş akışı | HTTP (`/{app}/{slug}`) | `returnDtoId` zorunlu (WF-002) |
+| `automation` | Entity satır olayına tepki | `entityId` + `operation` + `isQueue` | returnDtoId YASAK; aşağıdaki "Automation gerçekleri" |
+| `middleware` | Microservice/sayfa **çalışmadan önce** koşan guard/setter (auth, `user`/`settings` değişkenleri) | Bağlandığı uç çağrılınca (`middlewareIds`) | returnDtoId gerekmez; `set-user`/`variable`/`setcookie`/`redirect` yalnız bu tipte. **Ayrı rehberi var: `platform_guide('middleware')`** |
+
+## Step tipi × workflow tipi izin matrisi
+
+| Step | workflow | automation | middleware |
+|------|:-:|:-:|:-:|
+| start, condition, code, loop, table, query, http, workflow, email, file-upload | ✓ | ✓ | ✓ |
+| variable (Set Variable), set-user, setcookie, redirect | – | – | ✓ |
+| response | ✓ | – | ✓ |
+| convert | ✓ | – | – |
+| revert (Fail and Rollback) | – | ✓ | – |
+
+
+## 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;
+ölçüldü 2026-08-19, `anket-admin/anket-kaydet`).
+
+```jsonc
+{ "id": "<GUID>", "name": "loopQuestions", "type": "loop",
+  "rule": {
+    "stepType": "table",                        // ÇOCUK adımın tipi (loop değil)
+    "arrayExpression": "input.questions || []", // JS ifadesi → dizi
+    "stepRule": { /* çocuğun kendi rule'u — burada table create */ }
+  },
+  "branches": [{ "id": "<GUID>", "name": "success", "nextStepId": "<sonraki>" }] }
+```
+
+- **Çocuk kural `stepRule`'dur, `children` DEĞİL.** (Gateway **WF-018** ile yakalar: `stepRule` yoksa
+  ya da `arrayExpression` boşsa istek gitmez.) API DTO'sunda alan tekildir
+  (`StepRuleDto StepRule`); `children` gönderirsen `rule.Children` boş kalır ve loop
+  **`NullReferenceException`** ile patlar — hata mesajı `arrayExpression`'ı işaret ettiği için
+  seni ifadeyi suçlamaya iter, oysa sorun anahtar adıdır.
+- **Geçerli öğe `loopItem`'dır.** Çocuğun `fields[].value` / `filters[].value` ifadelerinde
+  `loopItem.<alan>` yazılır; `input` ve önceki adımlar (`createSurvey.data.id`) da görünmeye
+  devam eder.
+- **Çıktı `[{ item, result }]` dizisidir.** `result` çocuk adımın çıktısıdır; `table create`
+  için `{ id }`. Sonraki adımda `loopQuestions.data` ile okunur — **yazılan kayıtların id'sini
+  girdideki öğeyle eşleştirmenin yolu budur.**
+- **İkinci seviye eşleme için `code` adımına gerek yok:** ikinci loop'un `arrayExpression`'ı
+  zaten JS'tir, eşlemeyi orada yap:
+  ```js
+  (loopQuestions.data || []).reduce(function(acc, q){
+    var qid = q.result && q.result.id;
+    (input.options || []).filter(function(o){ return o.qkey === (q.item && q.item.key); })
+      .forEach(function(o){ acc.push({ label: o.label, question_id: qid }); });
+    return acc; }, [])
+  ```
+  İstemci alt kayıtları **düz** gönderir ve satırları `key`/`qkey` ile eşler — iç içe dizi
+  göndermek gerekmez (iç içe loop denenmedi; `loopItem` iç loop'ta gölgeleneceği için önerilmez).
+
+> **Table step'te `create`/`update` satır değerleri `fields[]`'tedir ve JS İFADESİDİR.**
+> `{ "fieldId": "<alan id>", "source": "expression", "value": "input.title", "order": 0 }` —
+> `PrepareParameters` her `fields[].value`'yu `EvaluateExpression` ile koşturur
+> (`TableStep.cs:392`). `delete` işleminde `fields` boş kalır, iş `filters[]`'dedir.
+
+> **GUID alanları HEX olmak zorunda.** Okunabilirlik için blok öneki kullanırken (`f1000001-…`)
+> hex olmayan harf koyma: `g1000001-…` gönderdiğimde platform
+> `The JSON value could not be converted to System.Guid` ile reddetti. Geçerli önek harfleri
+> yalnız `a`–`f`'tir.
+
+## Table step kuralları
+
+- `rule` içinde `datasourceId` + `entityId` zorunlu; `selectFields`/`filters` öğelerinde
+  **`fieldId` zorunlu** (yalnız `fieldSlug` yetmez → `EvaluateWorkflowStepFailedException`).
+- **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.
+  Join'in çıktısı sonraki adımlarda **iç içe** gelir: `step.data[0].course_id.code`.
+- **`rule.sort` ve `rule.limit` her table step'te verilir** — yoksa Studio'da workflow sayfası
+  `Cannot read properties of null (reading 'sortValue')` ile hiç açılmaz (**WF-013, block**).
+- Join path disiplini burada da **MS-007 (block)** ile aynıdır.
+- **Join varsa `rule.alias` (KÖK tablo alias'ı) zorunludur** ve kök entity'nin slug'ı olmalıdır:
+  join'in ON koşulunu `"<kökAlias>.<ilişkiAlanı>"` kurar, boş alias SQL'e `.<alan>` yazdırır ve
+  Postgres **`42601: zero-length delimited identifier`** ile reddeder — adım hiç çalışmaz, hata
+  sebebi söylemez. Gateway alias'ı kök `selectFields`'tan türetebiliyorsa doldurur, türetemezse
+  **WF-019** block'uyla isteği hiç göndermez. (Join'siz adımda alias eksikliği sorun çıkarmaz;
+  bu yüzden "join'siz çalışıyordu" gözlemi yanıltıcıdır.)
+- **İlişki alanı bu bağlamda DÜZ FK'dır.** `row_list` ilişki alanını her zaman
+  `{ id, <displayAlanı> }` nesnesi döndürür (her ilişki için join'i kendisi üretir); table adımı
+  yalnız **`joins` ile bildirdiğin** ilişkiyi nesneye çevirir. Bildirilmeyen alanda
+  `<alan>.<altAlan>` okuması `undefined` verir — hata değil, SESSİZ boş sonuç (rol dizisi
+  boşalırsa yetki kapısı yanlış karar verir; crm koşumu B-1). Gateway **WF-020** ile uyarır.
+  Dayanıklı yazım: `var v = x.role_id && x.role_id.id ? x.role_id.id : x.role_id;`
+
+```jsonc
+// Öğrencinin bir dersteki notlarını, ders bilgisiyle birlikte çeken table step
+"rule": {
+  "stepType": "table", "queryStepSourceType": "library", "isExpression": false,
+  "datasourceId": "<datasource id>", "entityId": "<grades entity id>",
+  "operation": "get", "alias": "grades", "isSingle": false,
+  "selectFields": [
+    { "alias": "grades",  "fieldId": "<score id>",  "fieldSlug": "score" },
+    { "alias": "grades",  "fieldId": "<weight id>", "fieldSlug": "weight" },
+    { "alias": "courses", "fieldId": "<code id>",   "fieldSlug": "code", "path": "<grades.course_id>" }
+  ],
+  "joins": [
+    { "alias": "courses", "entityId": "<courses id>", "fieldId": "<grades.course_id>",
+      "path": "<grades entity id>.<grades.course_id>", "joins": [] }
+  ],
+  "filters": [
+    { "alias": "grades", "fieldId": "<student_id>", "operator": "eq", "source": "expression",
+      "value": "input.student_id", "filterType": "single", "conditionType": "and",
+      "isRequired": true, "children": [], "order": 0 }
+  ],
+  "fields": [], "returnFields": [],
+  "sort":  { "name": "sortField", "type": "sortType", "source": "query-string" },
+  "limit": { "name": "limit", "offset": "offset", "source": "query-string" }
+}
+```
+- **Filtre `value` alanı JavaScript ifadesidir** (eval edilir): sabit → `"'EMP004'"` (tırnak
+  içinde), dinamik → `"input.employee_no + '|' + input.year"`, ternary/`new Date()` çalışır.
+  Tırnaksız sabit `X is not defined` hatası verir. İfadelerde kullanılabilen platform
+  fonksiyonları (`system.getPageUrl`, `file.excel`, `UtcNow()`, `crypto.*`…) ve bağlam için
+  **`platform_guide('expressions')`** — uydurma fonksiyon adı runtime 500'üdür.
+- Yazma step'lerinde (create/update): **yazılacak** alanlar `fields`, **okunacak** alanlar
+  `selectFields` — aynı alan ikisinde birden olamaz (`An item with the same key...`).
+- **Yazma step'inin çıktısı yalnız primary key'dir** (`<step>.data.id`); sonraki step'lerin ya
+  da response'un başka alana ihtiyacı varsa bunları **`returnFields`** ile iste
+  (`{ alias, fieldId, fieldSlug }` öğeleriyle) — `selectFields` write operasyonunda sessizce
+  yok sayılır.
+
+> **Gateway table step'lerinde `path`/`sort`/`limit` eksiklerini otomatik dolduruyor**
+> (yanıtta `gatewayNormalized`). Dolu değerlere dokunmaz; yanlış path yine WF/MS block'una takılır.
+
+## Response step'i gövdeyi `bodyExpression`'dan üretir
+
+`rule: { dataTransferObjectId }` **hiçbir şey döndürmez** (`result: null`). Çalışan şekil:
+
+```jsonc
+"rule": {
+  "queryStepSourceType": "library", "isExpression": false,
+  "bodyExpression": "{\n  success: true,\n  message: 'Kayıt oluşturuldu.',\n  id: new_enrollment.data.id\n}",
+  "httpStatusCode": 200, "headerExpression": "{  }",
+  "items": [], "returnType": "grouped", "enableDynamicFilters": false,
+  "selectFields": [], "fields": [], "returnFields": [], "filters": [], "joins": []
+}
+```
+
+Önceki step'in çıktısına **step adı + `.data`** ile erişilir (`existing_enrollment.data[0].id`,
+`new_enrollment.data.id`) — bu yüzden step adları geçerli JavaScript tanımlayıcısı olmalı.
+`returnDtoId` yine zorunludur (WF-002); sözleşmeyi o tanımlar, gövdeyi `bodyExpression` üretir.
+
+## `DtoId` verilen yerde `Behavior` de zorunlu
+
+`returnDtoId` verildiyse `returnBehavior`, `parameterDtoId` verildiyse `parameterBehavior`
+zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → ReturnBehavior
+.NotEmpty()`); atlamak `'Return Behavior' must not be empty` ile ilk denemeyi kırar. Değerler:
+`object` (varsayılan tercih) · `array` (akış DİZİ döndürüyorsa) · `primitive` (DTO primitive ise
+— aksi hâlde `WrongDtoBehaviorException`). **Gateway boş bırakılanı `object` ile doldurup
+`gatewayNormalized` ile bildirir**; dizi/primitive dönen akışlarda değeri sen ver.
+
+## Asgari iskelet (id'ler gerçek GUID olacak — placeholder'ları değiştir)
+
+```jsonc
+{
+  "name": "Product Lookup", "slug": "product-lookup", "type": "workflow",
+  "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>" }] },
+    { "id": "<GUID-3>", "name": "load_product", "type": "table",
+      "rule": { "stepType": "table", "datasourceId": "<datasource id>", "entityId": "<entity id>",
+                "operation": "get", "isSingle": true,
+                "selectFields": [{ "alias": "<entity slug>", "fieldId": "<alan id>", "fieldSlug": "name" }],
+                "filters": [{ "fieldId": "<alan id>", "fieldSlug": "name", "operator": "eq", "value": "input.productName" }],
+                "joins": [],
+                "sort":  { "name": "sortField", "type": "sortType", "source": "query-string" },
+                "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 }] },
+    { "id": "<GUID-5>", "name": "product_response", "type": "response",
+      "rule": { "bodyExpression": "{ name: load_product.data.name }", "httpStatusCode": 200,
+                "headerExpression": "{  }" }, "branches": [] }
+  ]
+}
+```
+
+## Automation gerçekleri (hr + qm projelerinde doğrulandı)
+
+- **`returnDtoId`/`parameterDtoId` automation'da YASAKTIR** (validator: "'Return Dto Id' must
+  be empty"). `returnBehavior: "object"` verilebilir.
+- **`state: 'unready'` automation için NORMALDİR ve tetiklemeyi etkilemez** — qm'deki çalışan
+  automation'lar da unready'dir; "Studio'dan aktifleştirme" diye bir işlem yoktur.
+- **Tetikleme kapısı üç alandır**, üçü de `automation` nesnesinde: `entityId` (tetikleyen
+  entity), `operation` (`create`/`update`/`delete`), **`isQueue` (false=anlık, true=kuyruklu;
+  null bırakılırsa tetikleme sorgusu HİÇ eşleşmez — automation sessizce ölü kalır)**.
+  `condition` opsiyonel JavaScript ifadesidir. `isActive` diye bir alan YOKTUR (yok sayılır).
+- `steps` hem üst seviyede hem `automation` içinde verilir (PLT-007); `response` step'i
+  kullanılamaz, hata yolu için `revert` vardır.
+- **Tetikleyen satıra `input` ile DEĞİL `row` ile erişilir**; update'te `previousRow`, işlemi
+  yapan kullanıcı `user` altındadır (`row.title`, `previousRow.user`, `user.id`). Step
+  `fields[]` öğelerinde `source: 'body'` + `value: '<ifade>'` kullanılır.
+- **`isQueue: false` senkron demek değildir.** Tetikleme ateşle-unut çalışır; satırı yazdıktan
+  hemen sonra sonucu okursanız automation'ın yazdığı satırı göremezsiniz. Kısa bir bekleme
+  sonrası tekrar okuyun.
+- Hem `row_create` ucundan hem `operation: 'create'` yapan bir microservice'ten tetiklenir —
+  ikisi de aynı hook'a düşer.
+- **Bilinen platform sınırı (P-03):** kısa aralıklı ardışık tetiklerde (özellikle `rows[]` ile
+  TOPLU `row_create`) automation yalnız ilk satır için tetiklenebiliyor — kayıp satırlar
+  `automation_histories`'te hiç görünmez. Otomasyonlu entity'lere satırları **tekil** yazın
+  (ya da sonradan `automation_trigger` ile telafi edin); toplu ekleme sonrası tetiklenmeyi
+  mutlaka sayarak doğrulayın.
+- Doğrulama: `automation_trigger` + `automation_histories` (ya da tetikleyen satırı yazıp
+  sonucu kontrol et).
+
+```jsonc
+{
+  "name": "New Hire Setup", "slug": "new-hire-setup", "type": "automation",
+  "returnBehavior": "object",
+  "steps": [ ...GUID id'li steps... ],
+  "automation": {
+    "name": "New Hire Setup", "slug": "new-hire-setup", "type": "automation",
+    "entityId": "<tetikleyen entity id>",
+    "operation": "create",
+    "isQueue": false,
+    "steps": [ ...aynı steps... ]
+  }
+}
+```
+
+## Sık hatalar (politika lint'inin yakaladıkları)
+
+- Bağlanmamış step grafı (WF-001, block) · workflow'da returnDtoId eksik (WF-002, block)
+- Yanlış tipte step (WF-005, block) · GUID olmayan step/branch id'si (WF-011, block)
+- 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)
+- İ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)
+
+## Hedefli değişiklik: `workflow_patch` yollarında İNDEKS KULLANMA
+
+Saklanan `steps` dizisinin sırası, `workflow_create`'e **gönderdiğin sıra değildir**. `/steps/5/...`
+gibi indeks yolları bu yüzden başka adımı yazar ve yanıt yine `applied: N` der — sessiz veri
+bozulması (crm koşumu B-4). Seçici kullan:
+
+```jsonc
+{ "op": "replace", "path": "/steps[id=<stepId>]/rule/expression", "value": "…" }
+{ "op": "replace", "path": "/steps[name=setUser]/rule/joins",     "value": [] }
+```
+
+Gateway seçiciyi gövde platforma **gitmeden** indekse çevirir, çözülemezse isteği hiç göndermez
+ve yanıtta `patchTargets` ile her op'un hangi adıma (ad + tip + id) indiğini söyler. Aynı seçici
+`microservice_patch`'te de çalışır (`/sourceParameters/joins[alias=customers]/path`).
+
+
+
+## Table adımının filtresi: `alias` YOKSA filtre SESSİZCE DÜŞER
+
+Bir `table` adımının `filters[]` girdisinde **`alias` zorunludur** ve entity'nin adım içindeki
+`alias` değeriyle birebir aynı olmalıdır. Eksikse filtre uygulanmaz; hata da çıkmaz.
+
+`operation: 'get'` + `isSingle: true` ile sonucu **felakete dönüşür**: sorgu tablodan rastgele
+(sıralamaya göre değişen) bir satır döndürür ve akış onu doğru kayıt sanar. Ölçüm (2026-08-18,
+`ik` zimmet akışı): `asset_id` verilmesine rağmen her koşumda başka bir demirbaş döndü; aynı
+kusur `operation: 'update'` filtresinde **yanlış satırı günceller**.
+
+```jsonc
+// ✘ filtre yok sayılır — istek 200 döner
+{ "fieldSlug": "id", "operator": "eq", "value": "input.asset_id", "fieldId": "<id alanı>" }
+
+// ✔ doğrusu
+{ "alias": "assets", "fieldId": "<id alanı>", "fieldSlug": "id", "operator": "eq",
+  "source": "expression", "value": "input.asset_id",
+  "filterType": "single", "conditionType": "and", "isRequired": true, "children": [], "order": 0 }
+```
+
+`source` da **`expression`** olmalı: verilmezse `body`'ye düşer ve `value` bir ifade değil
+**gövde alanı adı** sayılır — yine filtre kaybolur.

package/dist/resources/knowledge.js

@@ -0,0 +1,44 @@
+import { fileURLToPath } from 'node:url';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+const resourcesDirectory = dirname(fileURLToPath(import.meta.url));
+export function listKnowledgeFiles(kind) {
+    try {
+        return readdirSync(join(resourcesDirectory, kind)).filter(file => file.endsWith(kind === 'guides' ? '.md' : '.json'));
+    }
+    catch {
+        return [];
+    }
+}
+export function readKnowledgeFile(kind, file) {
+    return readFileSync(join(resourcesDirectory, kind, file), 'utf8');
+}
+export function registerKnowledgeResources(server) {
+    for (const kind of ['guides', 'examples']) {
+        const files = listKnowledgeFiles(kind);
+        const mimeType = kind === 'guides' ? 'text/markdown' : 'application/json';
+        server.registerResource(`${kind}-index`, `ngapps://${kind}/index`, {
+            title: kind === 'guides' ? 'Rehber dizini' : 'Altın örnek dizini',
+            description: kind === 'guides'
+                ? 'Platform iş kuralları rehberleri; modül tool\'larını kullanmadan önce okuyun.'
+                : 'Onaylanmış tam gövde örnekleri; boş org\'da şablon kaynağı budur.',
+            mimeType: 'application/json'
+        }, async (uri) => ({
+            contents: [{
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: JSON.stringify({ [kind]: files.map(file => `ngapps://${kind}/${file.replace(/\.(md|json)$/, '')}`) })
+                }]
+        }));
+        for (const file of files) {
+            const name = file.replace(/\.(md|json)$/, '');
+            server.registerResource(`${kind}-${name}`, `ngapps://${kind}/${name}`, {
+                title: name,
+                description: kind === 'guides' ? `${name} modülü iş kuralları rehberi` : `${name} altın örneği`,
+                mimeType
+            }, async (uri) => ({
+                contents: [{ uri: uri.href, mimeType, text: readKnowledgeFile(kind, file) }]
+            }));
+        }
+    }
+}

package/dist/resources/schemas/CreateDatasourceCommand.json

@@ -0,0 +1,54 @@
+{
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "nullable": true
+      },
+      "description": {
+        "type": "string",
+        "nullable": true
+      },
+      "dbName": {
+        "type": "string",
+        "nullable": true
+      },
+      "type": {
+        "$ref": "#/components/schemas/NgApps.Domain.Contexts.Datastore.Datasources.DatasourceType"
+      },
+      "host": {
+        "type": "string",
+        "nullable": true
+      },
+      "port": {
+        "type": "integer",
+        "format": "int32"
+      },
+      "properties": {
+        "nullable": true
+      },
+      "connectionOptions": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string",
+          "nullable": true
+        },
+        "nullable": true
+      }
+    },
+    "additionalProperties": false
+  },
+  "components": {
+    "schemas": {
+      "NgApps.Domain.Contexts.Datastore.Datasources.DatasourceType": {
+        "enum": [
+          "postgresql",
+          "mongodb"
+        ],
+        "type": "string",
+        "format": ""
+      }
+    }
+  }
+}