@appaflytech/zeyrek-ai-mcp 0.0.3 → 0.0.4

package/dist/resources/examples/middleware-authenticate.json

@@ -7,6 +7,7 @@
   "definition": {
     "name": "Authenticate",
     "slug": "authenticate",
+    "description": "Korunan uçların önünde koşar: token doğrular ve user değişkenini kurar.",
     "type": "middleware",
     "steps": [
       {
@@ -14,39 +15,65 @@
         "name": "start",
         "type": "start",
         "branches": [
-          { "id": "<GUID-2>", "name": "start", "type": "success", "nextStepId": "<GUID-3>" }
+          {
+            "id": "<GUID-2>",
+            "name": "start",
+            "type": "success",
+            "nextStepId": "<GUID-3>"
+          }
         ]
       },
       {
         "id": "<GUID-3>",
         "name": "token",
+        "description": "Çerezden/başlıktan ham token değerini çıkarır.",
         "type": "code",
         "rule": {
           "stepType": "code",
           "expression": "return system.validateToken(cookie.APP_Token)"
         },
         "branches": [
-          { "id": "<GUID-4>", "name": "success", "type": "success", "nextStepId": "<GUID-5>" }
+          {
+            "id": "<GUID-4>",
+            "name": "success",
+            "type": "success",
+            "nextStepId": "<GUID-5>"
+          }
         ]
       },
       {
         "id": "<GUID-5>",
         "name": "token_check",
+        "description": "Token yoksa 401 dalına, varsa doğrulamaya yönlendirir.",
         "type": "condition",
         "rule": {
           "stepType": "condition",
           "items": [
-            { "expression": "token.data.isValid && token.data.claims.userId", "branchId": "<GUID-6>" }
+            {
+              "expression": "token.data.isValid && token.data.claims.userId",
+              "branchId": "<GUID-6>"
+            }
           ]
         },
         "branches": [
-          { "id": "<GUID-6>", "name": "<GUID-6>", "type": "success", "nextStepId": "<GUID-8>" },
-          { "id": "<GUID-7>", "name": "else", "type": "success", "nextStepId": "<GUID-14>" }
+          {
+            "id": "<GUID-6>",
+            "name": "<GUID-6>",
+            "type": "success",
+            "nextStepId": "<GUID-8>"
+          },
+          {
+            "id": "<GUID-7>",
+            "name": "else",
+            "type": "success",
+            "nextStepId": "<GUID-14>"
+          }
         ]
       },
       {
         "id": "<GUID-8>",
         "name": "userTable",
+        "description": "Token sahibini users tablosundan rolleriyle birlikte okur.",
         "type": "table",
         "rule": {
           "stepType": "table",
@@ -55,24 +82,62 @@
           "operation": "get",
           "isSingle": true,
           "selectFields": [
-            { "alias": "users", "fieldId": "<id alanı id>", "fieldSlug": "id" },
-            { "alias": "users", "fieldId": "<email alanı id>", "fieldSlug": "email" },
-            { "alias": "users", "fieldId": "<first_name alanı id>", "fieldSlug": "first_name" }
+            {
+              "alias": "users",
+              "fieldId": "<id alanı id>",
+              "fieldSlug": "id"
+            },
+            {
+              "alias": "users",
+              "fieldId": "<email alanı id>",
+              "fieldSlug": "email"
+            },
+            {
+              "alias": "users",
+              "fieldId": "<first_name alanı id>",
+              "fieldSlug": "first_name"
+            }
           ],
           "filters": [
-            { "alias": "users", "fieldId": "<id alanı id>", "fieldSlug": "id", "operator": "eq", "source": "expression", "value": "token.data.claims.userId", "filterType": "single", "conditionType": "and", "isRequired": true, "children": [], "order": 0 }
+            {
+              "alias": "users",
+              "fieldId": "<id alanı id>",
+              "fieldSlug": "id",
+              "operator": "eq",
+              "source": "expression",
+              "value": "token.data.claims.userId",
+              "filterType": "single",
+              "conditionType": "and",
+              "isRequired": true,
+              "children": [],
+              "order": 0
+            }
           ],
           "joins": [],
-          "sort": { "name": "sortField", "type": "sortType", "source": "query-string" },
-          "limit": { "name": "limit", "offset": "offset", "source": "query-string" }
+          "sort": {
+            "name": "sortField",
+            "type": "sortType",
+            "source": "query-string"
+          },
+          "limit": {
+            "name": "limit",
+            "offset": "offset",
+            "source": "query-string"
+          }
         },
         "branches": [
-          { "id": "<GUID-9>", "name": "success", "type": "success", "nextStepId": "<GUID-10>" }
+          {
+            "id": "<GUID-9>",
+            "name": "success",
+            "type": "success",
+            "nextStepId": "<GUID-10>"
+          }
         ]
       },
       {
         "id": "<GUID-10>",
         "name": "setUser",
+        "description": "Bulunan kullanıcıyı 'user' değişkenine yazar; sonraki uçlar bunu okur.",
         "type": "set-user",
         "rule": {
           "stepType": "set-user",
@@ -80,12 +145,18 @@
           "dataTransferObjectId": "<user DTO id — opsiyonel; verilirse workflow_middleware_variables şemayı listeler>"
         },
         "branches": [
-          { "id": "<GUID-11>", "name": "success", "type": "success", "nextStepId": "<GUID-12>" }
+          {
+            "id": "<GUID-11>",
+            "name": "success",
+            "type": "success",
+            "nextStepId": "<GUID-12>"
+          }
         ]
       },
       {
         "id": "<GUID-12>",
         "name": "successResponse",
+        "description": "Kapıyı açar, istek asıl uca devam eder.",
         "type": "response",
         "rule": {
           "stepType": "response",
@@ -98,6 +169,7 @@
       {
         "id": "<GUID-14>",
         "name": "unauthorizedResponse",
+        "description": "Kimliksiz/geçersiz isteği 401 ile keser.",
         "type": "response",
         "rule": {
           "stepType": "response",
@@ -117,78 +189,202 @@
     "relationFieldTrap": "user_roles.role_id bir table adımında NESNE DEĞİL düz FK'dır (row_list her ilişki için join'i kendisi üretir, table adımı yalnız joins'te bildirileni çevirir). 'p.role_id.slug' undefined döner, roller sessizce boşalır ve Authorized her zaman false olur. Aşağıdaki ifade iki şekle de dayanır.",
     "steps": [
       {
-        "id": "<GUID-R1>", "name": "rolesTable", "type": "table",
+        "id": "<GUID-R1>",
+        "name": "rolesTable",
+        "type": "table",
         "rule": {
-          "stepType": "table", "datasourceId": "<datasource id>", "entityId": "<user_roles entity id>",
-          "operation": "get", "alias": "user_roles", "isSingle": false,
+          "stepType": "table",
+          "datasourceId": "<datasource id>",
+          "entityId": "<user_roles entity id>",
+          "operation": "get",
+          "alias": "user_roles",
+          "isSingle": false,
           "selectFields": [
-            { "alias": "user_roles", "fieldId": "<user_roles.id>", "fieldSlug": "id" },
-            { "alias": "user_roles", "fieldId": "<user_roles.role_id>", "fieldSlug": "role_id" }
+            {
+              "alias": "user_roles",
+              "fieldId": "<user_roles.id>",
+              "fieldSlug": "id"
+            },
+            {
+              "alias": "user_roles",
+              "fieldId": "<user_roles.role_id>",
+              "fieldSlug": "role_id"
+            }
           ],
           "filters": [
-            { "alias": "user_roles", "fieldId": "<user_roles.user_id>", "operator": "eq", "source": "expression",
-              "value": "userTable.data.id", "filterType": "single", "conditionType": "and",
-              "isRequired": true, "children": [], "order": 0 }
+            {
+              "alias": "user_roles",
+              "fieldId": "<user_roles.user_id>",
+              "operator": "eq",
+              "source": "expression",
+              "value": "userTable.data.id",
+              "filterType": "single",
+              "conditionType": "and",
+              "isRequired": true,
+              "children": [],
+              "order": 0
+            }
           ],
-          "joins": [], "fields": [], "returnFields": [],
-          "sort": { "name": "sortField", "type": "sortType", "source": "query-string" },
-          "limit": { "name": "limit", "offset": "offset", "source": "query-string" }
+          "joins": [],
+          "fields": [],
+          "returnFields": [],
+          "sort": {
+            "name": "sortField",
+            "type": "sortType",
+            "source": "query-string"
+          },
+          "limit": {
+            "name": "limit",
+            "offset": "offset",
+            "source": "query-string"
+          }
         },
         "branches": [
-          { "id": "<GUID-R2>", "name": "success", "type": "success", "nextStepId": "<GUID-R3>" },
-          { "id": "<GUID-R2b>", "name": "fail", "type": "fail", "nextStepId": "<GUID-14>" }
+          {
+            "id": "<GUID-R2>",
+            "name": "success",
+            "type": "success",
+            "nextStepId": "<GUID-R3>"
+          },
+          {
+            "id": "<GUID-R2b>",
+            "name": "fail",
+            "type": "fail",
+            "nextStepId": "<GUID-14>"
+          }
         ]
       },
       {
-        "id": "<GUID-R3>", "name": "allRoles", "type": "table",
+        "id": "<GUID-R3>",
+        "name": "allRoles",
+        "type": "table",
         "rule": {
-          "stepType": "table", "datasourceId": "<datasource id>", "entityId": "<roles entity id>",
-          "operation": "get", "alias": "roles", "isSingle": false,
+          "stepType": "table",
+          "datasourceId": "<datasource id>",
+          "entityId": "<roles entity id>",
+          "operation": "get",
+          "alias": "roles",
+          "isSingle": false,
           "selectFields": [
-            { "alias": "roles", "fieldId": "<roles.id>", "fieldSlug": "id" },
-            { "alias": "roles", "fieldId": "<roles.slug>", "fieldSlug": "slug" }
+            {
+              "alias": "roles",
+              "fieldId": "<roles.id>",
+              "fieldSlug": "id"
+            },
+            {
+              "alias": "roles",
+              "fieldId": "<roles.slug>",
+              "fieldSlug": "slug"
+            }
           ],
-          "filters": [], "joins": [], "fields": [], "returnFields": [],
-          "sort": { "name": "sortField", "type": "sortType", "source": "query-string" },
-          "limit": { "name": "limit", "offset": "offset", "source": "query-string" }
+          "filters": [],
+          "joins": [],
+          "fields": [],
+          "returnFields": [],
+          "sort": {
+            "name": "sortField",
+            "type": "sortType",
+            "source": "query-string"
+          },
+          "limit": {
+            "name": "limit",
+            "offset": "offset",
+            "source": "query-string"
+          }
         },
         "branches": [
-          { "id": "<GUID-R4>", "name": "success", "type": "success", "nextStepId": "<GUID-R5>" },
-          { "id": "<GUID-R4b>", "name": "fail", "type": "fail", "nextStepId": "<GUID-14>" }
+          {
+            "id": "<GUID-R4>",
+            "name": "success",
+            "type": "success",
+            "nextStepId": "<GUID-R5>"
+          },
+          {
+            "id": "<GUID-R4b>",
+            "name": "fail",
+            "type": "fail",
+            "nextStepId": "<GUID-14>"
+          }
         ]
       },
       {
-        "id": "<GUID-R5>", "name": "setUser", "type": "set-user",
+        "id": "<GUID-R5>",
+        "name": "setUser",
+        "description": "Bulunan kullanıcıyı 'user' değişkenine yazar; sonraki uçlar bunu okur.",
+        "type": "set-user",
         "rule": {
           "stepType": "set-user",
           "expression": "(function () {\n  var link = rolesTable.data || [];\n  var all  = allRoles.data || [];\n  var slugs = link.map(function (ur) {\n    var rid = ur.role_id && ur.role_id.id ? ur.role_id.id : ur.role_id;\n    var match = all.filter(function (r) { return r.id === rid; })[0];\n    return match && match.slug;\n  }).filter(function (s) { return !!s; });\n  return Object.assign({}, userTable.data, { roles: slugs, roles_csv: ',' + slugs.join(',') + ',' });\n})()",
           "dataTransferObjectId": "<user DTO id — opsiyonel>"
         },
-        "branches": [{ "id": "<GUID-R6>", "name": "success", "type": "success", "nextStepId": "<GUID-R7>" }]
+        "branches": [
+          {
+            "id": "<GUID-R6>",
+            "name": "success",
+            "type": "success",
+            "nextStepId": "<GUID-R7>"
+          }
+        ]
       },
       {
-        "id": "<GUID-R7>", "name": "roleGate", "type": "condition",
-        "rule": { "stepType": "condition", "items": [{ "expression": "Authorized(user.roles)", "branchId": "<GUID-R8>" }] },
+        "id": "<GUID-R7>",
+        "name": "roleGate",
+        "type": "condition",
+        "rule": {
+          "stepType": "condition",
+          "items": [
+            {
+              "expression": "Authorized(user.roles)",
+              "branchId": "<GUID-R8>"
+            }
+          ]
+        },
         "branches": [
-          { "id": "<GUID-R8>", "name": "<GUID-R8>", "type": "success", "nextStepId": null },
-          { "id": "<GUID-R9>", "name": "else", "type": "fail", "nextStepId": "<GUID-F>" }
+          {
+            "id": "<GUID-R8>",
+            "name": "<GUID-R8>",
+            "type": "success",
+            "nextStepId": null
+          },
+          {
+            "id": "<GUID-R9>",
+            "name": "else",
+            "type": "fail",
+            "nextStepId": "<GUID-F>"
+          }
         ]
       },
       {
-        "id": "<GUID-F>", "name": "forbiddenResponse", "type": "response",
+        "id": "<GUID-F>",
+        "name": "forbiddenResponse",
+        "type": "response",
         "rule": {
           "stepType": "response",
           "bodyExpression": "{ success: false, message: 'Bu işlem için yetkiniz yok.' }",
-          "httpStatusCode": 403, "headerExpression": "{  }"
+          "httpStatusCode": 403,
+          "headerExpression": "{  }"
         },
         "branches": []
       }
     ],
-    "acceptance": "Dört testle kabul edilir: (1) rolü olan kullanıcı korumalı ucu çağırır → 200; (2) rolü olmayan kullanıcı → 403; (3) kimliksiz çağrı (microservice_execute anonymous:true) → 401; (4) roleIds boş bir uç aynı middleware'e bağlıyken kimliği doğrulanmış herkese açık kalır (Authorized boş rol listesinde true döner)."
+    "acceptance": "Dört testle kabul edilir: (1) rolü olan kullanıcı korumalı ucu çağırır → 200; (2) rolü olmayan kullanıcı → 403; (3) kimliksiz çağrı (microservice_execute anonymous:true) → 401; (4) roleIds boş bir uç aynı middleware'e bağlıyken kimliği doğrulanmış herkese açık kalır (Authorized boş rol listesinde true döner).",
+    "description": "Middleware çeşidi."
   },
   "consumptionExample": {
     "note": "Kimlik kapsaması: uca middleware'i bağla (definition.middlewareIds) + owner filtresi expression yap. qm kanıtı: sy-users-get-my-profile.",
-    "middlewareIds": ["<authenticate workflow id>"],
-    "filter": { "fieldId": "<owner alanı id>", "operator": "eq", "source": "expression", "value": "user.id", "filterType": "single", "conditionType": "and", "isRequired": false, "children": [], "order": 0 }
+    "middlewareIds": [
+      "<authenticate workflow id>"
+    ],
+    "filter": {
+      "fieldId": "<owner alanı id>",
+      "operator": "eq",
+      "source": "expression",
+      "value": "user.id",
+      "filterType": "single",
+      "conditionType": "and",
+      "isRequired": false,
+      "children": [],
+      "order": 0
+    }
   }
 }

package/dist/resources/examples/workflow-basic.json

@@ -1,11 +1,12 @@
 {
   "_meta": {
     "synthetic": true,
-    "note": "hr projesinde doğrulanmış şekil. Kurallar: step/branch id'leri GERÇEK GUID ve global benzersiz (RowAlreadyExists); DtoId verilen yerde Behavior zorunlu; table rule'da datasourceId + fieldId zorunlu; filtre value JavaScript ifadesi; preview girdisi previewPayload anahtarıyla."
+    "note": "hr projesinde doğrulanmış şekil. Kurallar: step/branch id'leri GERÇEK GUID ve global benzersiz (RowAlreadyExists); DtoId verilen yerde Behavior zorunlu; table rule'da datasourceId + fieldId zorunlu; filtre value JavaScript ifadesi; preview girdisi previewPayload anahtarıyla. bağlanmamış fail dalı hataya düşerse start'taki global-error dalına gider (IStep.cs:74-86)."
   },
   "definition": {
     "name": "Product Lookup",
     "slug": "product-lookup",
+    "description": "Ada göre tek ürün getirir; bulunamazsa hata yoluna düşer.",
     "type": "workflow",
     "parameterDtoId": "<girdi DTO id: { productName: string }>",
     "returnDtoId": "<çıktı DTO id: { name, price }>",
@@ -22,12 +23,20 @@
             "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",
+        "description": "input.productName ile ürünü okur; tek kayıt bekler.",
+        "caution": "Ad benzersiz değil: aynı adda birden çok ürün varsa ilkini alır, hiç yoksa sessizce boş döner.",
         "type": "table",
         "rule": {
           "stepType": "table",
@@ -77,6 +86,7 @@
       {
         "id": "<GUID-6>",
         "name": "Response",
+        "description": "Bulunan ürünün adını 200 ile döner.",
         "type": "response",
         "rule": {
           "stepType": "response",
@@ -85,10 +95,22 @@
           "headerExpression": "{  }"
         },
         "branches": []
+      },
+      {
+        "id": "<GUID-8>",
+        "name": "onError",
+        "description": "Akış patlarsa hata kodunu ve mesajını 500 ile döner.",
+        "type": "response",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "({ code: error.code, message: error.message })",
+          "httpStatusCode": 500
+        },
+        "branches": []
       }
     ]
   },
   "automationVariant": {
     "note": "Automation: returnDtoId/parameterDtoId YASAK (validator reddeder), returnBehavior 'object' verilebilir; state=unready NORMALDİR ve tetiklemeyi etkilemez. Tetikleme kapısı automation nesnesindeki entityId + operation + isQueue (false=anlık, true=kuyruk; null=asla tetiklenmez!). steps hem üst seviyede hem automation içinde (PLT-007); response yasak, hata yolu revert."
   }
-}
+}

package/dist/resources/guides/component.md

@@ -38,8 +38,11 @@ component_get   → tek tipin TAM sözleşmesi, üç katman birleşik:
 - Yük `events[].payload`'dadır ama akışa **`event.data` ile GELMEZ**: motor yükü komponentin
   KENDİ prop'una yazar (`FlowMachine.onEmit` → `setNode`) ve akışı emit'in `params`'ıyla başlatır.
   Yani `payload` anahtarları prop adlarıdır ve `self.<anahtar>` ile okunur (ya da
-  `value.type:'property'`); `reads` alanı yükte olmayan prop'ları söyler. `event.data` yalnız
-  `html` komponentinin `fireEvent` aksiyonlarında dolar.
+  `value.type:'property'`); `reads` alanı yükte olmayan prop'ları söyler. `event.data`
+  `html`'in `fireEvent` aksiyonlarında ve `params` da gönderen 2026-08-27 kuşağında
+  (`eventcalendar` · `importwizard` · `kanban` · `signature` · `stepper`) dolar — `kanban` ve
+  `eventcalendar` yükü `self`'e HİÇ yazmaz, yalnız `event.data` ile okunur (ayrım
+  `component_get` sözleşme notlarında).
 - Akış bağlama: `flow_create` → `page_schema_patch set_event`. İstisna: `html` komponentinin
   aksiyonları kendi `flow` prop'uyla bağlanır (`platform_guide('html')`).
 
@@ -88,7 +91,7 @@ Her şema düğümünde iki sözlük vardır; ikisi de ortak render katmanında
 
 | `appearance` | Değerler | Anlamı |
 |---|---|---|
-| `heightType` | `auto` · `fixed` | `auto`: içerik kadar (önerilen — Kural 1d); `fixed`: `blocks.h × 10px` |
+| `heightType` | `auto` · `fixed` · `fill` | `auto`: içerik kadar (önerilen — Kural 1d); `fixed`: `blocks.h × 10px`; `fill`: **kalanı doldur** — ebeveynin bıraktığı yer (ızgarada `height:100%`, flex sütununda `flex:1 1 auto`, flex satırında `align-self:stretch`). Tam ekran yerleşim kabuğu bununla kurulur, bkz. `platform_guide('layout')` |
 | `marginType` / `marginValue` | `normal` · `none` · `custom` + px | Dış boşluk: normal=5px, custom=`marginValue` |
 | `paddingType` / `paddingValue` | `normal` · `none` · `custom` + px | Droppable kapların iç boşluğu: normal=10px |
 | `alignType` | `left` · `center` · `right` | İçerik hizalama (destekleyen komponentlerde) |

package/dist/resources/guides/external-component.md

@@ -0,0 +1,129 @@
+# Kendi komponentinizi yazmak
+
+Hazır katalog (`component_list`) ihtiyacınızı karşılamıyorsa üç seçeneğiniz var,
+bu sırayla deneyin:
+
+1. **Hazır komponenti zorlayın.** `component_get` ile prop'lara bakın; çoğu
+   "yok" sanılan davranış bir prop ya da event kombinasyonuyla çıkar.
+2. **`html` kaçış kapısı.** Tek seferlik bir görsel için yeterli — bkz.
+   `platform_guide('html')`. Kalıcı, tekrar kullanılacak bir şey değilse burada
+   durun.
+3. **Kendi komponentinizi yayınlayın.** Aynı ihtiyaç birden fazla sayfada
+   tekrarlanıyorsa, prop/event sözleşmesi gerekiyorsa ya da `html` içinde
+   yönetilemeyecek kadar davranış varsa doğru yol budur. Bu rehberin konusu.
+
+Yayınlanan komponent platformun kendi komponentlerinden ayırt edilmez:
+sayfaya sürüklenir, prop'ları property panelinde düzenlenir, event'leri flow'a
+bağlanır, tema değişkenlerini alır. Studio toolbox'ında **"Your Components"**
+başlığı altında listelenir.
+
+## Akış
+
+```
+external_component_scaffold   → yerel iskelet (element.mjs + manifest.json)
+        ↓ (element.mjs'i yazın, manifest'i gerçek prop/event'lerinize göre düzenleyin)
+external_component_publish    → kayıt + paket yüklenir, doğrulama raporu döner
+        ↓ (rapor block içeriyorsa düzeltip tekrar publish — depolamaya yazılmadı)
+        ↓ taslak: Studio önizlemesinde görünür, yayınlanmış uygulamada görünmez
+external_component_activate   → yayına alır (yalnız metadata; kesinti yok)
+        ↓
+page_schema_patch             → add_component ile sayfaya koyun
+```
+
+Aktivasyondan sonra komponent `component_list` / `component_get` çıktısında
+normal katalog kaydı gibi döner; `add_component` micro-op'unda `type` olarak
+slug'ı kullanın.
+
+## Sözleşme
+
+Host element'e şema prop'larını **JS property** olarak yazar — attribute değil,
+böylece dizi ve nesneler bozulmadan geçer. Yanına iki kanal koyar:
+
+| Property | İçerik |
+|---|---|
+| şemadaki her prop | çözülmüş değer; yalnız değişen key'ler yeniden yazılır |
+| `zxContext` | `{ elementId, appearance, states, isRequired, editorMode, language }` |
+| `zxMachine` | platform yüzeyi (aşağıda) |
+
+Element geriye **tek bir DOM olayıyla** konuşur: `zx-emit`, detail'i
+`{ name, data?, setter?, flowId?, params? }`.
+
+- `name` manifest'te bildirdiğiniz event adı olmalı; bildirilmemiş bir ad
+  flow'a bağlanamaz.
+- `setter: true` verirseniz `data` içindeki değer aynı adlı prop'a geri yazılır —
+  `value` gibi iki yönlü davranan proplar için budur.
+
+`zxMachine` sayılı bir yüzeydir; burada olmayan hiçbir şeye erişemezsiniz:
+`getProps`, `getComponents`, `getComponentProps`, `getState`/`setState`,
+`getVariable`/`setVariable`, `getStorage`/`setStorage`,
+`getLanguage`/`setLanguage`, `t`, `checkAuthorization`, `user`, `pageParams`,
+`emit`, `on`.
+
+## Yasaklar — yayınlamayı reddeder
+
+Paket sunucuda AST taramasından geçer. Şunlardan biri varsa paket **depolamaya
+hiç yazılmaz**:
+
+`eval`, `new Function` / `Function(...)`, dinamik `import()`,
+`document.cookie`, `window.machine`, `navigator.serviceWorker.register`,
+`document.write`, `localStorage.clear()` / `sessionStorage.clear()`.
+
+Tarama AST üzerinde çalışır: bir string sabitinin içindeki `eval` kelimesi bulgu
+değildir, `eval(...)` çağrısı bulgudur.
+
+## Uyarılar — rapora yazılır, aktivasyonda onay ister
+
+Dış ağ erişimi (`fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`),
+doğrudan `localStorage`/`sessionStorage` erişimi, `window.X = ...` ataması,
+`innerHTML`/`outerHTML` ataması, ve manifest'te bildirip element'te
+karşılığını yazmadığınız proplar.
+
+Uyarısı olan bir sürüm `acknowledgeWarnings: true` olmadan aktive edilemez.
+Uyarıyı gördüğünüzde önce gerçekten gerekli mi diye bakın: veriyi flow ile
+almak `fetch`'ten, `zxMachine.setStorage` doğrudan storage'dan iyidir.
+
+## Kurallar
+
+- Slug `x-` ile başlamak zorunda (`^x-[a-z][a-z0-9-]*$`). Bu önek platform
+  slug'larıyla çakışmayı imkânsız kılar.
+- Tek `export default`, `HTMLElement` türeten bir sınıf.
+- Prop adları DOM'u bozacak adlar olamaz: `id`, `class`, `className`, `style`,
+  `slot`, `name`, `children`, `innerHTML`, `outerHTML`, `textContent`, `zx*`,
+  `on*`.
+- `manifest.definition.blocks` boş olamaz — ızgara ayak izi olmayan komponent
+  ölçeklenemez.
+- Prop tipleri platformun tanıdığı kümeden olmalı (`text`, `long-text`,
+  `number`, `switch`, `dropdown`, `array`, `object`, `flow`, `icon`, `color`,
+  `date`, …). Yeni bir prop tipi uyduramazsınız.
+- Paket 2 MB'ı geçemez.
+- Renk, boşluk, tipografi için `--ng-*` tema değişkenlerini kullanın; sabit renk
+  yazarsanız komponent kullanıcının temasına uymaz.
+
+## Sürümler ve geri alma
+
+Paketler değişmezdir: aynı `(slug, version)` ikinci kez yayınlanamaz, düzeltme
+yeni bir sürüm demektir. `external_component_versions` geçmişi ve her sürümün
+doğrulama raporunu verir; `external_component_activate` ile eski bir sürümü
+aktive etmek geri alma olarak çalışır. Aktivasyon yalnız metadata değiştirir —
+platform yeniden başlamaz, açık oturumlar bozulmaz.
+
+## Editor modu
+
+`zxContext.editorMode` true olduğunda element Studio kanvasında statik bir
+önizleme olarak duruyor: zamanlayıcı kurmayın, ağ çağrısı yapmayın, tıklamayı
+işlemeyin. Kanvasta etkileşim host tarafından zaten engellenir, ama gereksiz iş
+yapmamak kanvası hızlı tutar.
+
+## Geliştirici kiti
+
+Platform, npm paketi olmadan servis eder:
+
+- `{studio}/component-kit/zeyrek-component.d.ts` — protokolün tip bildirimleri
+- `{studio}/component-kit/harness.html` — platformsuz deneme sayfası
+- `{studio}/component-kit/example-rating-stars.mjs` — çalışan örnek
+- `GET {tenant}/{project}/components/external/manifest-schema` — manifest için
+  JSON Schema; izin verilen prop tipleri ve rezerve adlar sunucudaki kural
+  setinden **üretilir**, statik bir kopya olmadığı için sapmaz.
+
+`external_component_scaffold` bu sözleşmeye uyan bir iskeleti yerel dizine
+zaten yazar; kit, iskeleti elle düzenlerken referans olarak işinize yarar.