systa-mcp 1.3.0 → 1.5.0

package/README.md

@@ -101,14 +101,14 @@ claude mcp add systa \
 
 ## Araçlar (tools)
 
-Toplam **64 araç** vardır; `tools/list` yanıtı anahtarın kapsamına göre filtrelenir
+Toplam **79 araç** vardır; `tools/list` yanıtı anahtarın kapsamına göre filtrelenir
 (bkz. "Scope-aware araç listesi"). Aşağıdakiler en sık kullanılan çekirdek araçlardır —
 tam katalog `list_capabilities` ile keşfedilir.
 
 | Araç                    | Açıklama                                                                                                                                                                                                                               |
 | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `list_requests`         | Talepleri listele (limit/offset/search/statusId) — `request.read`                                                                                                                                                                      |
-| `get_request`           | Tek bir talebi id ile getir — `request.read`                                                                                                                                                                                           |
+| `get_request`           | Tek bir talebi talep numarasıyla getir — `request.tabs.general.view`                                                                                                                                                                   |
 | `list_projects`         | Projeleri listele — `project.read`                                                                                                                                                                                                     |
 | `create_request`        | Talep oluştur (title/description/companyId/statusId/assignedTo) — `request.create`                                                                                                                                                     |
 | `add_request_comment`   | Talebe yorum ekle (düz metin otomatik TipTap'e sarılır) — `request.comment.create` + `request.tabs.comments.view`                                                                                                                      |
@@ -117,12 +117,33 @@ tam katalog `list_capabilities` ile keşfedilir.
 | `upload_file_to`        | Yerel dosyaları multipart olarak ek diye yükler (talep/proje/görev kartı/orphan) — `file.upload`                                                                                                                                       |
 | `list_capabilities`     | **Bu anahtar ne yapabilir?** — scope-filtreli modül/endpoint kataloğu (yetkisiz endpoint görünmez); her metot için safety class + gereken izin. Ayrıca SysTa platform özeti (overview), TR glossary ve her modülün açıklamasını içerir |
 | `describe_module`       | Bir modülün (örn. request/kanban/plan) amacı, kavramları ve çağrılabilir endpoint'leri — kullanıcı niyetini doğru modüle eşlemek için (oryantasyon)                                                                                    |
-| `describe_endpoint`     | Tek endpoint detayı: alan tipleri (fields), güvenlik sınıfı, açıklama — çağrı gövdesini kurmadan önce                                                                                                                                  |
+| `describe_endpoint`     | Tek endpoint detayı: alan tipleri, güvenlik sınıfı ve tam HTTP Response Contract v2 — çağrı gövdesini kurmadan ve yanıtı zincirlemeden önce                                                                                            |
 
 `systa_api_call` ile, özel bir aracı olmayan herhangi bir endpoint çağrılabilir
 (örn. `POST /requests`, `POST /requests/42/comments`). Anahtarın scope'u dışındaki
 çağrılar `403` döner.
 
+### Alt form hazırlama
+
+Alt form (`sub-forms`), ana talep formu (`form`) ile aynı modül değildir. Ajan önce
+`list_capabilities({module:"sub-forms"})`, ardından kullanacağı uçlar için
+`describe_endpoint` çağırmalıdır. Önerilen taslak akışı:
+
+1. `POST /sub-forms` ile `isPublic:false` bir form kabuğu oluşturun. `parentFormId`
+   backend tarafından şirketin aktif talep formundan çözülür; istemci göndermemelidir.
+2. Bölüm, alan ve kuralları ayrı ayrı yazmak yerine
+   `PUT /sub-forms/:id/save` ile tek transaction'da kaydedin. Yeni öğelerde `tempId`,
+   alan-bölüm ilişkisinde `sectionTempId` kullanılır; yanıt gerçek id haritalarını verir.
+3. Kullanım biçimini yalnız `embed` veya `request_attach` binding'iyle tanımlayın.
+4. `GET /sub-forms/:id/preview` HTML değil `{form, sections, fields, preview:true}`
+   JSON payload'ı döndürür. Query/rule/title/correlation test uçları kalıcı ayar yazmaz.
+5. Taslak özetini kullanıcıya göstermeden ve açık onay almadan publish/public erişim,
+   allowed origin, webhook, periodic veya correlation özelliklerini etkinleştirmeyin.
+
+Tam alan türleri, atomik save gövdesi, binding kararları ve hata kurtarma akışı paketle
+birlikte kurulan `SKILL.md` içindedir. Sürüm yükselttikten sonra skill'i yenilemek için
+`npx -y systa-mcp@latest --install-skill` komutunu yeniden çalıştırın.
+
 ### Dosya ekleri (download_request_file / upload_file_to)
 
 `systa_api_call` JSON-only olduğundan binary taşıyamaz — dosya ekleri için bu iki

package/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 1.3.0
+version: 1.5.0
 name: systa
 description: |
   Drive SysTa (Talep Takip Sistemi / SysTa) — a
@@ -15,12 +15,14 @@ description: |
   "bana/şuna ata", "yorum ekle", "durumu değiştir /
   tamamla / kapat", "üzerimdeki işler", "proje aç",
   "kanban kartı ekle", "onaya sun", "onayla/reddet",
-  "izin talebi", "rapor al / dışa aktar", "sürüm
-  oluştur". Use when (EN): "create a SysTa request",
+  "izin talebi", "alt form hazırla / oluştur", "rapor
+  al / dışa aktar", "sürüm oluştur". Use when (EN):
+  "create a SysTa request",
   "log a ticket", "assign / reassign", "add a comment",
   "move/close the ticket", "show my open work", "create
   project", "add task card", "request approval",
-  "approve/reject", "export report", "create release".
+  "approve/reject", "design/create a sub-form", "export
+  report", "create release".
   Multi-tenant (vendor schema) aware; resolves names →
   ids; honors dynamic required fields. NOT for: editing
   SysTa source code, running psql/DB migrations directly,
@@ -87,6 +89,7 @@ Short shared vocabulary. Use these words with the user; never expose raw REST pa
 | SLA                   | SLA                 | Süre taahhütleri (ilk yanıt, çözüm). Instance bir talebe bağlanır; pause/resume edilebilir.                                                                     |
 | Onay                  | Approval            | Toplu onaya gönderme + onayla/reddet; plan onayı ve talep onayı ayrı akışlar.                                                                                   |
 | Sürüm                 | Release             | Yazılım sürüm yönetimi: liste → item → onay → Go/No-Go → deployment workflow.                                                                                   |
+| Alt form              | Sub-form            | Talep formuna gömülen veya talep akışına bağlanan, bölüm/alan/kural/binding içeren ek veri toplama şeması. Ana istek formu (`form`) ile aynı şey değildir.      |
 | Vendor şema           | Vendor schema       | Multi-tenant izolasyon; her vendor ayrı schema (`vendor_xxx`). Public referans alınmaz.                                                                         |
 
 ### Anahtar kelime → modül eşlemesi (keyword index)
@@ -96,56 +99,58 @@ yanıtındaki `glossary` alias'larının ayna kopyasıdır (MCP yokken de geçer
 ASCII'dir — eşleştirmede aksanı yok say. Modülü bulduktan sonra `describe_module(modül)`
 veya `describe_endpoint` ile gövdeyi netleştir.
 
-| Doğal dil (alias)                                            | Modül           | Birincil giriş                                                                                  |
-| ------------------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------- |
-| talep, talepler, is, destek talebi                           | request         | list_requests / create_request                                                                  |
-| geciken, overdue, gecikmis, sla ihlali, deadline gecmis      | request/sla     | list_requests(overdue:true / slaBreached:true)                                                  |
-| toplu guncelle, hepsini, birden cok talep                    | request         | bulk_update_requests                                                                            |
-| kullanici bul, isim cozumle, kime, hangi ahmet               | user            | resolve_user_by_name / list_users                                                               |
-| sirket bul, kategori bul, ekip bul, id cozumle, lookup       | multiple        | list_lookup(kind:'company'/'category'/'team'/...)                                               |
-| projeyi klonla, projeyi cogalt, duplicate project            | project         | duplicate_project                                                                               |
-| snapshot fark, baseline karsilastir, plan diff               | plan            | compare_plan_baseline                                                                           |
-| yorumlar, ekler, degisiklik gecmisi, denetim                 | request         | list_request_comments / list_request_files / list_request_history                               |
-| yorum yaz, tablo, referans, #125, ##1809, kod blogu, baslik  | request         | add_request_comment — govde TipTap JSON; tablo/liste commentTextJson ile, referanslar DUZ METIN |
-| gorev, task, kart, card                                      | kanban          | manage_request_card / move_request_card                                                         |
-| pano, board, kanban / kolon, column, asama, liste            | kanban          | get_request_board / create_request_board                                                        |
-| durum gecisi onizle, izinli gecisler, hangi duruma gecebilir | request         | list_allowed_transitions                                                                        |
-| plan modu, sprint kapsami, plan mode setup                   | plan            | create_plan_mode                                                                                |
-| durum, oncelik, atanan, planla, denetim, gecmis              | request         | get_request / list_requests                                                                     |
-| tahmini efor, planlanan sure (estimatedEffort)               | request         | update_request (TAHMIN alani, defter DEGIL)                                                     |
-| efor gir, efor yaz, calistigim sure, efor defteri, mesai     | effort          | log_effort / list_effort_targets / list_effort_entries                                          |
-| eksik efor girisim var mi, efor uyumu                        | effort          | get_effort_compliance                                                                           |
-| proje, klonla                                                | project         | list_projects / create_project                                                                  |
-| onaya sunma, snapshot, sprint, sprinti kapat, optimize et    | plan            | submit_plan_for_approval / create_plan_baseline                                                 |
-| onay, onayla, reddet                                         | approvals       | list_pending_approvals / respond_to_approval                                                    |
-| onay tipleri, kime onaya gonderelim                          | approvals       | list_approval_types                                                                             |
-| red nedeni, neden reddedildi, gecerli red sebepleri          | approvals       | list_rejection_reasons                                                                          |
-| bu talep neden dondu, neden yazamiyorum, kilitli alan        | approvals       | get_request_freeze                                                                              |
-| sla, sure taahhudu                                           | sla             | (sla endpoints)                                                                                 |
-| release, surum, go/no-go, deployment                         | release         | create_release_list / add_release_item (listeyi ID ile hedefle)                                 |
-| surum numarasi, versionLabel, ayni gun iki liste             | release         | create_release_list -> id + versionLabel (tarih DEGIL)                                          |
-| musaitlik, izin (leave), vekil                               | user/automation | systa_api_call /user-availability, /user-leaves                                                 |
-| vendor, sirket, musteri                                      | company         | systa_api_call GET /companies                                                                   |
-| organizasyon birimi, departman, bolum, birim                 | department      | GET /api/departments                                                                            |
-| takim, ekip, team                                            | team            | GET /api/teams                                                                                  |
-| yetki paketi, izin (permission)                              | security        | (bundle/permission endpoints)                                                                   |
-| alt form, sub-form                                           | forms           | systa_api_call GET /forms/:id                                                                   |
-| rapor, raporlama, disa aktar, export, excel, csv             | report          | systa_api_call /reports/preview,/reports/export                                                 |
-| ozel sorgu, sorgu, query builder, ad-hoc, veri cek           | query-builder   | querybuilder_describe_fields / \_execute_query                                                  |
-| hesap tablosu, gridpad, tablo, excel, spreadsheet, hucre     | spreadsheet     | GET /api/spreadsheets                                                                           |
-| dosya, ek, attachment, yukle, upload, indir, download        | file            | upload_file_to / download_request_file                                                          |
-| bildirim, notification, uyari, okundu, push                  | notification    | GET /api/notifications                                                                          |
-| yetenek, beceri, skill, otomatik etiketleme                  | skill           | GET /api/skills                                                                                 |
-| duyuru, announcement, bildiri, ilan                          | announcement    | GET /api/announcements                                                                          |
-| urun guncellemesi, surum notu, yenilikler, changelog         | product-update  | GET /api/product-updates                                                                        |
-| not, kisisel not, hatirlatma                                 | note            | GET /api/dashboard/notes                                                                        |
-| yer imi, favori, bookmark, kisayol                           | bookmark        | GET /api/dashboard/bookmarks                                                                    |
-| degerlendirme, puanlama, memnuniyet, geri bildirim           | ratings         | POST /api/ratings                                                                               |
-| anket, oylama, karar alalim, ekibe soralim, secenek sun      | decisions       | systa_api_call POST /requests/:n/decisions                                                      |
-| github, repo, pull request, commit, issue aktar              | github          | systa_api_call /github/me/{connection,repos,import,push}                                        |
-| gosterge paneli, dashboard, widget, ozet, grafik, panel      | dashboard       | GET /api/dashboard/init                                                                         |
-
-> Bu tablo, katalogdaki ~25 modülün kullanıcı-yüzeyli olanlarından bir alt küme kapsar. Listede olmayan
+| Doğal dil (alias)                                            | Modül             | Birincil giriş                                                                                  |
+| ------------------------------------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------- |
+| talep, talepler, is, destek talebi                           | request           | list_requests / create_request                                                                  |
+| geciken, overdue, gecikmis, sla ihlali, deadline gecmis      | request/sla       | list_requests(overdue:true / slaBreached:true)                                                  |
+| toplu guncelle, hepsini, birden cok talep                    | request           | bulk_update_requests                                                                            |
+| kullanici bul, isim cozumle, kime, hangi ahmet               | user              | resolve_user_by_name / list_users                                                               |
+| sirket bul, kategori bul, ekip bul, id cozumle, lookup       | multiple          | list_lookup(kind:'company'/'category'/'team'/...)                                               |
+| projeyi klonla, projeyi cogalt, duplicate project            | project           | duplicate_project                                                                               |
+| snapshot fark, baseline karsilastir, plan diff               | plan              | compare_plan_baseline                                                                           |
+| yorumlar, ekler, degisiklik gecmisi, denetim                 | request           | list_request_comments / list_request_files / list_request_history                               |
+| yorum yaz, tablo, referans, #125, ##1809, kod blogu, baslik  | request           | add_request_comment — govde TipTap JSON; tablo/liste commentTextJson ile, referanslar DUZ METIN |
+| gorev, task, kart, card                                      | kanban            | manage_request_card / move_request_card                                                         |
+| pano, board, kanban / kolon, column, asama, liste            | kanban            | get_request_board / create_request_board                                                        |
+| durum gecisi onizle, izinli gecisler, hangi duruma gecebilir | request           | list_allowed_transitions                                                                        |
+| plan modu, sprint kapsami, plan mode setup                   | plan              | create_plan_mode                                                                                |
+| durum, oncelik, atanan, planla, denetim, gecmis              | request           | get_request / list_requests                                                                     |
+| tahmini efor, planlanan sure (estimatedEffort)               | request           | update_request (TAHMIN alani, defter DEGIL)                                                     |
+| efor gir, efor yaz, calistigim sure, efor defteri, mesai     | effort            | log_effort / list_effort_targets / list_effort_entries                                          |
+| eksik efor girisim var mi, efor uyumu                        | effort            | get_effort_compliance                                                                           |
+| proje, klonla                                                | project           | list_projects / create_project                                                                  |
+| onaya sunma, snapshot, sprint, sprinti kapat, optimize et    | plan              | submit_plan_for_approval / create_plan_baseline                                                 |
+| onay, onayla, reddet                                         | approvals         | list_pending_approvals / respond_to_approval                                                    |
+| onay tipleri, kime onaya gonderelim                          | approvals         | list_approval_types                                                                             |
+| red nedeni, neden reddedildi, gecerli red sebepleri          | approvals         | list_rejection_reasons                                                                          |
+| bu talep neden dondu, neden yazamiyorum, kilitli alan        | approvals         | get_request_freeze                                                                              |
+| sla, sure taahhudu                                           | sla               | (sla endpoints)                                                                                 |
+| release, surum, go/no-go, deployment                         | release           | create_release_list / add_release_item (listeyi ID ile hedefle)                                 |
+| surum numarasi, versionLabel, ayni gun iki liste             | release           | create_release_list -> id + versionLabel (tarih DEGIL)                                          |
+| musaitlik, uygunluk                                          | user-availability | systa_api_call GET /user-availability                                                           |
+| izin (leave), izin hakkı, takım izin takvimi                 | leave-management  | systa_api_call /leave-management, /user-leaves                                                  |
+| vekil, delegate, proxy                                       | automation-rules  | systa_api_call /automation-rules                                                                |
+| vendor, sirket, musteri                                      | company           | systa_api_call GET /companies                                                                   |
+| organizasyon birimi, departman, bolum, birim                 | company           | GET /api/departments                                                                            |
+| takim, ekip, team                                            | team              | GET /api/teams                                                                                  |
+| yetki paketi, izin (permission)                              | security          | (bundle/permission endpoints)                                                                   |
+| alt form, sub-form, subform, ek form, mini form              | sub-forms         | systa_api_call GET /sub-forms/:id                                                               |
+| rapor, raporlama, disa aktar, export, excel, csv             | report            | systa_api_call /reports/preview,/reports/export                                                 |
+| ozel sorgu, sorgu, query builder, ad-hoc, veri cek           | query-builder     | querybuilder_describe_fields / \_execute_query                                                  |
+| hesap tablosu, gridpad, tablo, excel, gridPad, hucre         | gridpad           | GET /api/gridpads                                                                               |
+| dosya, ek, attachment, yukle, upload, indir, download        | file              | upload_file_to / download_request_file                                                          |
+| bildirim, notification, uyari, okundu, push                  | notification      | GET /api/notifications                                                                          |
+| yetenek, beceri, skill, otomatik etiketleme                  | skills            | GET /api/skills                                                                                 |
+| duyuru, announcement, bildiri, ilan                          | announcements     | GET /api/announcements                                                                          |
+| urun guncellemesi, surum notu, yenilikler, changelog         | product-updates   | GET /api/product-updates                                                                        |
+| not, kisisel not, hatirlatma                                 | dashboard         | GET /api/dashboard/notes                                                                        |
+| yer imi, favori, bookmark, kisayol                           | dashboard         | GET /api/dashboard/bookmarks                                                                    |
+| degerlendirme, puanlama, memnuniyet, geri bildirim           | ratings           | POST /api/ratings                                                                               |
+| anket, oylama, karar alalim, ekibe soralim, secenek sun      | decisions         | systa_api_call POST /requests/:n/decisions                                                      |
+| github, repo, pull request, commit, issue aktar              | github            | systa_api_call /github/me/{connection,repos,import,push}                                        |
+| gosterge paneli, dashboard, widget, ozet, grafik, panel      | dashboard         | GET /api/dashboard/init                                                                         |
+
+> Bu tablo, dinamik katalogdaki kullanıcı-yüzeyli modüllerin bir alt kümesini kapsar. Listede olmayan
 > bir kelime için `list_capabilities` çağır — anahtarının erişebildiği güncel modül/alias
 > kümesini döndürür (kapsam-filtreli; yetkisiz modül görünmez).
 
@@ -155,7 +160,7 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 2. **No jargon.** Don't narrate "calling describe_endpoint", "POST /api/requests", "resolving statusId". Speak in the product's user verbs.
 3. **Detect language and reply in it.** If the user writes Turkish, answer in Turkish; if English, English. Field keys and enum values passed to the API stay as the API expects (`statusKey`, `priority=high`) — only the conversation is localized.
 4. **Smart defaults + ask one thing at a time.** Apply opinionated defaults from the intent summary (`channel='API'`, `priority='normal'`, assignee=self for "bana", `strategy='any_one'`/`'all_required'` per module). Ask **one** genuinely-missing thing, never a batch ("ver bana başlık, şirket, durum, öncelik, kategori" YASAK). Never invent a `title`, a password, a webhook URL, or a secret — ask for those.
-5. **Resolve dynamic required fields up front.** Before a create/mutation, resolve the entity's required fields _for this vendor_ (e.g. `statusId` via `GET /api/statuses`, `companyId` from `who-am-i`, approver name → `userId` via user lookup). Don't submit a half-filled body and let it 400 — pre-resolve, then submit. Forms with dynamic schemas: pull the schema first (via `systa_api_call`, e.g. `GET /forms/:id`) so required fields are known.
+5. **Resolve dynamic required fields up front.** Before a create/mutation, resolve the entity's required fields _for this vendor_ (e.g. `statusId` via `GET /api/statuses`, `companyId` from `who-am-i`, approver name → `userId` via user lookup). Don't submit a half-filled body and let it 400 — pre-resolve, then submit. For a main request form use the `form` module; for an alt form use `describe_endpoint('/api/sub-forms/:id','GET')` and then read `GET /api/sub-forms/:id`. Never substitute `/forms/:id` for an alt form.
 6. **Safety tiers gate confirmation.** `read_only` → just do it. `mutating`/`idempotent` → do it, then report. **`destructive`** (revoke access, delete, hard removal) and live side-effecting actions (publish, send invite, advance release workflow, test webhook) → show a one-line "şunu yapacağım" and get an explicit OK first. Publishing (announcement/release notes/product update) is **never** auto-published — show a summary, get approval.
 7. **Don't over-ask scope.** `companyId`/`userId`/`vendorSchema` come from `who-am-i`; don't ask the user for them when a single sane value exists.
 
@@ -164,9 +169,33 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 You don't memorize 600+ endpoints. Discover on demand.
 
 - **`list_capabilities`** — call when you need to find _which_ module/intent serves the user's verb, or when the user asks "ne yapabilirsin / what can you do". Returns scope-filtered modules (this key's reachable surface), each with a short summary, category, safety class and required permission. Use it to pick the right tool before acting; never claim a capability the catalog doesn't list for this key.
-- **`describe_endpoint`** — call when you've picked a tool and need its exact required fields, body shape, enums and defaults before submitting. Prefer this over guessing a body. It returns the field schema (`fieldKey`, type, required, enum, default) so you can pre-fill dynamic required fields and avoid `VALIDATION_FAILED`.
+- **`describe_endpoint`** — call with both `path` and `method` when you've picked a tool and need its exact required fields, body shape, enums and defaults before submitting. Prefer this over guessing a body. It returns the field schema plus the verified HTTP Response Contract v2 (status, transport, content type, envelope and data/body schema); use returned IDs, handles and pagination fields for the next step instead of guessing them.
+- **`describe_module`** — call after you've mapped the user's intent to a module. Returns the module's purpose, its key concepts, its endpoints, and **`entryPoints`**: the calls that need **no id up front**. A chain always starts at an entry point — calling an id-bearing endpoint first just returns 404/400.
 - **Rule of thumb:** ambiguous intent → `list_capabilities` first; chosen intent but unsure of body → `describe_endpoint`; clear intent + known body → act directly. For REST fallback, the equivalents are `GET /api/api-keys/me/capabilities` (preview of reachable endpoints) and the per-endpoint field schema returned by the MCP `describe_endpoint`.
 
+### Çağrı sırası (prerequisites)
+
+A compact listing marks a method with `hasPrerequisites: true` when it needs an id you must obtain **first**. `describe_endpoint` returns the detail:
+
+```json
+"prerequisites": [
+  {
+    "parameter": "requestId",
+    "collection": "/api/requests",
+    "producedBy": [
+      { "path": "/api/requests", "method": "GET", "field": "id", "evidence": "response-field" }
+    ]
+  }
+]
+```
+
+- `source` is `"path"` when the id goes into the URL, `"body"` when it is a **required body field** (e.g. `POST /api/approvals` requires `requestId` in the body — it never appears in the path).
+- `producedBy` lists the endpoints that **produce** that id; the first candidate carries the strongest evidence.
+- `evidence: "response-field"` — the producer's response contract really contains `field`; chain it directly.
+- `evidence: "collection-path"` — the link comes from the REST path structure (the producer's response schema is dynamic); call the producer and read the id off the returned record.
+
+So the flow is: **user intent → `list_capabilities` (module) → `describe_module` (`entryPoints`) → `describe_endpoint` (fields + `prerequisites`) → walk the chain top-down → perform the action.** Never invent an id; always take it from a producer endpoint.
+
 ## Çekirdek iş akışları (core workflows)
 
 Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from the catalog. Resolve ids first, act, then summarize in the user's language.
@@ -326,6 +355,136 @@ Gövdede geçen şu düz metin tokenları otomatik olarak **tıklanabilir rozete
 
 - No dedicated tool — drive via `systa_api_call`. `userId`=self (sormadan), `leaveType='annual'`, `isHalfDay=false`, dates normalized to `YYYY-MM-DD` ("yarın/cuma" → tarih), `returnToWorkDate` = next working day after end. "izinlerim" → `systa_api_call` `GET /user-leaves/me`. Needs the `user.leave.self` scope.
 
+### Alt form hazırla / oluştur (design a sub-form) — `systa_api_call` + `sub-forms`
+
+Alt form, ana talep formu değildir. `form` modülü ana talep şemasını; `sub-forms`
+modülü ise bağımsız/gömülü ek veri toplama şemasını yönetir. Alt form; form meta
+bilgisi, bölümler, alanlar, kurallar ve nerede çalışacağını belirleyen binding'lerden
+oluşur. Dedicated create aracı yoktur; keşif ve tüm çağrılar `systa_api_call` ile yapılır.
+
+#### 1. İhtiyacı kısa bir forma çevir
+
+Kullanıcıdan doğal dilde şu kararları çıkar; yalnız gerçekten eksik olan **tek** kararı sor:
+
+- Amaç ve görünen ad. `formKey`, `sectionKey`, `fieldKey` değerlerini ajan üretir:
+  küçük harf + rakam + alt çizgi, en az 2 karakter (`musteri_geri_bildirim` gibi).
+- Kullanım biçimi: doğrudan/gömülü veri toplayıp talep açma → formMode
+  'create_request' + bindingType 'embed'; mevcut talep içinde görev/ek iş formu →
+  formMode 'create_task' + bindingType 'request_attach'; ikisi de gerekiyorsa formMode
+  'both'. Binding türü yalnız 'embed' veya 'request_attach' olabilir.
+- Bölümler ve alanlar. Alan türleri:
+  `text`, `textarea`, `number`, `currency`, `email`, `phone`, `date`, `datetime`,
+  `select`, `multiselect`, `checkbox`, `radio`, `file`, `hidden`, `custom_regex`,
+  `image`, `signature`, `location`, `rating`, `switch`, `richtext`.
+  Veri türü `string|number|boolean|date|file|json`; seçenekli alanlarda `optionsConfig`,
+  zorunlu alanlarda `isRequired:true`, iki kolon düzeninde `colSpan:1|2` kullan.
+- Otomasyon, dış erişim veya yayın isteği açıkça söylenmediyse kural, webhook,
+  periyodik çalışma, public erişim, captcha secret ya da allowed origin ekleme.
+  Güvenli taslak varsayılanı `isPublic:false` ve yayında-değil durumudur.
+
+Etiket/başlık gibi çevrilebilir alanları katalog şemasının istediği i18n nesnesiyle
+gönder (örn. `{tr:'E-posta',en:'Email'}`). Kullanıcının verdiği mevcut id'leri başka
+vendor'da yeniden kullanma; company/team/user/status/category/board/formRule adlarını
+önce bu vendor içinde çöz.
+
+#### 2. Uçları ve güncel şemayı keşfet
+
+1. `list_capabilities({module:'sub-forms'})` çağır. Ayrıca binding ve gönderi işi
+   varsa `describe_module('sub-form-bindings')` / `describe_module('sub-form-submissions')`
+   kullan. Modül görünmüyorsa kapsam dışıdır; endpoint uydurma.
+2. En az şu uçları `describe_endpoint(path,method)` ile oku:
+   `POST /api/sub-forms`, `PUT /api/sub-forms/:id/save`, `GET /api/sub-forms/:id/preview`
+   ve seçilen binding gerekiyorsa `POST /api/sub-forms/:id/bindings`.
+3. Mevcut bir form değişiyorsa önce `GET /api/sub-forms/:id` oku; kullanıcı açıkça
+   kaldır demedikçe mevcut section/field/rule kimliklerini koru.
+
+#### 3. Önce taslak şemayı oluştur, sonra atomik kaydet
+
+1. `POST /api/sub-forms` ile yalnız temel formu oluştur: `formName`, üretilmiş
+   `formKey`, amaçtan seçilen `formMode`, `isPublic:false`. Kullanım biçimi belliyse
+   `initialBindingType` da gönderilebilir; 'request_attach' binding'de `formRuleId`
+   henüz yoksa binding pasif oluşur ve daha sonra tamamlanır. `parentFormId` gönderme:
+   backend bunu şirketin aktif ana talep formundan server-authoritative çözer ve
+   create/update/save sırasında istemci değerini yok sayar.
+2. Dönen alt form `id`'sini al. Bölüm/alan/kuralı tek tek yazmak yerine
+   `PUT /api/sub-forms/:id/save` kullan; bu işlem tek transaction'da kaydeder ve
+   form sürümünü artırır. Gövde:
+
+   ```json
+   {
+     "form": { "formName": "Müşteri Geri Bildirimi", "formMode": "create_request" },
+     "sections": [
+       {
+         "tempId": "sec_contact",
+         "sectionKey": "iletisim",
+         "title": { "tr": "İletişim" },
+         "displayOrder": 0
+       }
+     ],
+     "fields": [
+       {
+         "tempId": "fld_email",
+         "sectionTempId": "sec_contact",
+         "fieldKey": "email",
+         "fieldType": "email",
+         "dataType": "string",
+         "label": { "tr": "E-posta" },
+         "isRequired": true,
+         "displayOrder": 0,
+         "colSpan": 2
+       }
+     ],
+     "rules": [],
+     "deletedSectionIds": [],
+     "deletedFieldIds": [],
+     "deletedRuleIds": []
+   }
+   ```
+
+   Yeni bileşenlerde `tempId`, alan-bölüm ilişkisinde `sectionTempId` kullan. Yanıttaki
+   `sectionIdMap`, `fieldIdMap`, `ruleIdMap` gerçek id'leri verir. Mevcut bileşende
+   `id` gönder. `deleted*Ids` listelerine yalnız kullanıcının açıkça kaldırdığı mevcut
+   id'leri koy; listede olmayan öğeleri “eksik geldi” diye silme.
+
+3. İlk create'te binding kurulmadıysa `POST /api/sub-forms/:id/bindings` çağır.
+   'embed' site/portal içinde doğrudan çalışır. 'request_attach' mevcut talep akışına
+   `formRuleId` ile bağlanır; rule çözülene kadar pasif kalabilir. Rastgele talep/proje
+   id'sini binding diye gönderme.
+
+#### 4. Doğrula; kullanıcı onayı olmadan yayınlama
+
+- `GET /api/sub-forms/:id` ile kaydedilmiş tanımı, ardından
+  `GET /api/sub-forms/:id/preview` ile `{form,sections,fields,preview:true}` önizleme
+  payload'ını oku. Bu uç HTML/render edilmiş ekran döndürmez; görünümü istemci çizer.
+- Dinamik query alanında `POST /api/sub-forms/:id/fields/:fieldId/test-query` çağrısı
+  yapılandırmayı kaydetmez ama tanımlı prefix-set/regex veya sandboxed read-only SQL'i
+  gerçekten çalıştırır. Yerleşik doğrulama ve lookup setlerini önce
+  `GET /api/sub-forms/query/prefix-sets` ile keşfet. Kurallar için
+  `POST /api/sub-forms/:id/rules/test` side-effect üretmeyen dry-run'dır.
+- Kullanıcıya ad, kullanım biçimi, bölüm/alan listesi, zorunlu alanlar, binding ve
+  varsa kuralları tek özetle göster. `PATCH /api/sub-forms/:id/publish` yalnız açık
+  “yayınla/devreye al” onayından sonra çağrılır. Taslak hazırlama isteği yayınlama
+  izni değildir. Yayından kaldırma da canlı akışı durdurur; önceden onay al.
+
+#### 5. İleri özellikleri yalnız ihtiyaç varsa ekle
+
+- Public/embed: allowed origins tam origin biçimindedir (`https://ornek.com`, trailing
+  slash yok). Kullanıcı domaini ve public erişimi açıkça istemeden ekleme/açma.
+- Başlık şablonu: kaydetmeden önce `POST /api/sub-forms/:id/title-preview` ile canlı
+  gönderim işlemcisine eşdeğer önizleme al.
+- Korelasyon: önce `GET/POST /api/sub-forms/correlation-groups`; bir alt form yalnız
+  tek gruba üye olabilir. Etkin ayarda `groupId`, en az bir `matchField` ve kimlik rolü
+  (`customer_id|phone|email`) gerekir. `POST /api/sub-forms/:id/correlation/preview`
+  geçmiş gönderiler üstünde dry-run yapar; sonucu görmeden korelasyonu etkinleştirme.
+- Webhook dış sisteme yan etki üretir. Hedef URL/olay kullanıcıya ait karardır; secret
+  isteme veya sohbette gösterme. Oluşturma, test ve secret rotasyonu öncesi onay al.
+
+Hata kurtarma: `VALIDATION_FAILED` gelirse aynı ucu yeniden `describe_endpoint` ile
+oku, yalnız hatalı alanı düzeltip bir kez dene. `403` için başka binding/modül yoluyla
+yetki aşmaya çalışma. `409` formKey çakışmasında kullanıcı adını değiştirme; aynı
+anlamı koruyan yeni bir key öner. Silme uçları soft-delete olsa bile güvenilir bir
+restore ucu garanti edilmez; kaldırma öncesi kullanıcı onayı al.
+
 ### Rapor al / dışa aktar (report) — `systa_api_call` (no named tool)
 
 - No dedicated tool — drive via `systa_api_call`. Önce önizle (`POST /reports/preview`, read-only), sonra dışa aktar (`POST /reports/export`, `format='xlsx'` unless "csv"). `reportType` is the required pivot (request/sla/user/organization/project/lifecycle/subform) — infer from intent. Resolve columns via `GET /reports/columns` if the user only named a type. "bu ay/geçen ay" → dynamic date filter. (For ad-hoc/free queries prefer the `querybuilder_*` tools.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systa-mcp",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "MCP stdio server for SysTa (Talep Takip Sistemi) — lets AI agents (Claude, Codex) use the SysTa REST API via a scoped API key. Zero npm dependencies (native Node).",
   "type": "commonjs",
   "main": "server.js",

package/server.js

@@ -50,10 +50,27 @@ const INSTRUCTIONS = [
   '     ve SENIN kullanicini (user) icerir — "ben / bana ata / uzerimdeki" niyetinde assignedTo',
   '     icin user.id BURADAN gelir. Kullanicinin dogal dilini (talep/gorev/efor/pano/durum/atanan...)',
   '     bunlarla dogru modul ve endpoint ile eslestir.',
-  '  2) `describe_module(module)` (opsiyonel) — bir modulun (orn. request/kanban/plan) amacini,',
-  '     kavramlarini ve cagirabilecegin endpointleri topluca gorursun.',
-  '  3) `describe_endpoint(path, method)` cagir — o endpoint için alan tiplerini (fields),',
-  '     guvenlik sinifini ve aciklamayi al; sonra cagri govdesini buna gore kur.',
+  '  2) `describe_module(module)` — modulun amacini, kavramlarini, cagirabilecegin endpointleri VE',
+  '     `entryPoints`i verir. `entryPoints` ONCEDEN BIR KIMLIK GEREKTIRMEYEN cagrilardir:',
+  '     zincir HER ZAMAN buradan baslar. Kimlik isteyen bir ucu once denemek 404/400 uretir.',
+  '  3) `describe_endpoint(path, method)` cagir — alan tiplerini (fields), guvenlik sinifini,',
+  '     tam HTTP Response Contract v2 bilgisini ve `prerequisites` alanini al.',
+  '',
+  'CAGRI SIRASI (prerequisites) — ONEMLI:',
+  '  Kompakt listede bir metodun `hasPrerequisites: true` olmasi, o ucun ONCE baska bir cagriyla',
+  '  elde edilmesi gereken bir kimlige ihtiyac duydugunu soyler. Ayrintiyi `describe_endpoint`',
+  '  verir:',
+  '    prerequisites: [{ parameter, collection, producedBy: [{ path, method, field?, evidence }] }]',
+  '  - `parameter`  : gereken kimlik (orn. requestId).',
+  "  - `source`     : `path` -> URL'de doldurulur. `body` -> ZORUNLU govde alanidir ve",
+  "                   path'te HIC gorunmez (orn. POST /api/approvals govdesinde requestId).",
+  '  - `producedBy` : o kimligi URETEN uclar. Ilk aday en guclu kanitlidir.',
+  '  - `evidence`   : `response-field` -> uretici ucun yanit semasinda `field` gercekten var,',
+  '                   dogrudan zincirle. `collection-path` -> baglanti REST yapisindan kurulmus;',
+  '                   uretici ucu cagir ve donen kayittan kimligi oku.',
+  '  Yani akis sudur: kullanicinin niyeti -> `list_capabilities` ile MODUL -> `describe_module`',
+  '  ile `entryPoints` -> gereken ucta `describe_endpoint` -> `prerequisites` zincirini yukaridan',
+  '  asagi cagir -> asil islemi yap. Kimlik UYDURMA; her zaman uretici uctan al.',
   '',
   'GUVENLIK SINIFI (safetyClass): read_only (guvenli okuma) | idempotent (tekrarlanabilir)',
   '  | mutating (durum degistirir) | destructive (geri-alinamaz — dikkatli ol, gerekirse onayla).',
@@ -77,6 +94,17 @@ const INSTRUCTIONS = [
   '  binary tasiyamaz; diger her endpoint icin `systa_api_call` (method+path) kullan — path ve',
   '  govdeyi describe_endpoint ciktisindan kur (path icin /api on-eki opsiyonel, otomatik normalize edilir).',
   '',
+  'ALT FORM (sub-form) HAZIRLAMA: Ana talep formu `form`, ek/mini form ise `sub-forms`',
+  'moduludur; `/forms/:id` alt-form detayi DEGILDIR. Once `list_capabilities({module:"sub-forms"})`,',
+  'sonra POST `/sub-forms` + PUT `/sub-forms/:id/save` semalarini `describe_endpoint` ile oku.',
+  'Taslagi POST `/sub-forms` ile isPublic=false olustur; section/field/rule degisikliklerini',
+  'tempId + sectionTempId kullanarak TEK transaction olan PUT `/sub-forms/:id/save` ile kaydet.',
+  'Binding yalniz `embed` veya `request_attach` olur. parentFormId server-authoritative oldugu',
+  'icin gonderme. GET `/sub-forms/:id/preview` render edilmis HTML degil, form/section/field',
+  'onizleme payloadidir. Query/rule/title/correlation preview uclari kalici config yazmaz.',
+  'Kullaniciya taslak ozeti gostermeden ve acik onay almadan publish, public/origin, webhook,',
+  'periodic veya korelasyon ozelligini etkinlestirme; silme/yayindan kaldirma icin de onay al.',
+  '',
   'YORUM YAZMA (comment) — ONEMLI, ZENGIN METIN SOZLESMESI:',
   '  Yorum govdesi DUZ METIN DEGIL, TipTap JSON dokumanidir: {type:"doc", content:[...]}.',
   '  `add_request_comment` duz metni tek paragrafa sarar — TABLO, BASLIK, LISTE, KOD BLOGU',
@@ -396,6 +424,292 @@ const systaUploadMultipart = async (apiPath, method, filePaths) => {
 const unwrapCapabilities = (res) =>
   res && res.data && res.data.data ? res.data.data : res && res.data;
 
+const capabilityProjectionPath = (projection, filters = {}) => {
+  const query = new URLSearchParams({ projection });
+  for (const [key, value] of Object.entries(filters)) {
+    if (value !== undefined && value !== null && value !== '') {
+      query.set(key, String(value));
+    }
+  }
+  return `/api-keys/me/capabilities?${query.toString()}`;
+};
+
+const RESPONSE_TRANSPORTS = new Set([
+  'json',
+  'binary',
+  'text',
+  'sse',
+  'redirect',
+  'empty',
+  'webhook_ack',
+]);
+const RESPONSE_ENVELOPES = new Set([
+  'systa_success_v1',
+  'systa_error_v1',
+  'raw_json',
+  'legacy_error',
+  'none',
+]);
+const RESPONSE_SCHEMA_TYPES = new Set([
+  'null',
+  'boolean',
+  'object',
+  'array',
+  'number',
+  'integer',
+  'string',
+]);
+const RESPONSE_BINARY_DELIVERY_MODES = new Set(['buffer', 'stream']);
+const isPlainObject = (value) =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const validSchemaVariants = (schema) => {
+  const variants = schema.oneOf || schema.anyOf;
+  if (variants === undefined) {
+    return { valid: true, variants: null };
+  }
+  return {
+    valid:
+      Array.isArray(variants) &&
+      variants.length > 0 &&
+      (!schema.oneOf || typeof schema.branchReason === 'string') &&
+      variants.every(isValidResponseJsonSchema),
+    variants,
+  };
+};
+
+const validSchemaTypes = (schema) => {
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  return {
+    valid: types.length > 0 && types.every((type) => RESPONSE_SCHEMA_TYPES.has(type)),
+    types,
+  };
+};
+
+const validObjectResponseSchema = (schema) => {
+  const properties = schema.properties;
+  const hasProperties = isPlainObject(properties) && Object.keys(properties).length > 0;
+  const dynamic =
+    (schema.additionalProperties === true || isPlainObject(schema.additionalProperties)) &&
+    typeof schema.dynamicReason === 'string';
+  const requiredValid =
+    schema.required === undefined ||
+    (Array.isArray(schema.required) &&
+      schema.required.every((key) => typeof key === 'string' && key in properties));
+  const childrenValid =
+    !hasProperties || Object.values(properties).every(isValidResponseJsonSchema);
+  const additionalValid =
+    !isPlainObject(schema.additionalProperties) ||
+    isValidResponseJsonSchema(schema.additionalProperties);
+  return (hasProperties || dynamic) && requiredValid && childrenValid && additionalValid;
+};
+
+function isValidResponseJsonSchema(schema) {
+  if (!isPlainObject(schema)) {
+    return false;
+  }
+  const variantResult = validSchemaVariants(schema);
+  if (!variantResult.valid) {
+    return false;
+  }
+  if (schema.type === undefined) {
+    return Boolean(
+      variantResult.variants || schema.$ref !== undefined || schema.const !== undefined,
+    );
+  }
+  const typeResult = validSchemaTypes(schema);
+  if (!typeResult.valid) {
+    return false;
+  }
+  if (typeResult.types.includes('array') && !isValidResponseJsonSchema(schema.items)) {
+    return false;
+  }
+  return !typeResult.types.includes('object') || validObjectResponseSchema(schema);
+}
+
+const hasValidResponseBasics = (response) =>
+  isPlainObject(response) &&
+  Number.isInteger(response.status) &&
+  response.status >= 100 &&
+  response.status <= 599 &&
+  RESPONSE_TRANSPORTS.has(response.transport) &&
+  RESPONSE_ENVELOPES.has(response.envelope);
+
+const hasValidResponseContentType = (response) => {
+  const bodyless = response.transport === 'redirect' || response.transport === 'empty';
+  return bodyless
+    ? response.contentType === null && response.envelope === 'none'
+    : typeof response.contentType === 'string' && Boolean(response.contentType.trim());
+};
+
+const hasValidDynamicContentType = (response) => {
+  const hasDynamicMetadata =
+    response.dynamicContentType !== undefined ||
+    response.contentTypePattern !== undefined ||
+    response.contentTypeSource !== undefined;
+  if (response.contentType !== '*/*') {
+    return !hasDynamicMetadata;
+  }
+  if (
+    response.transport !== 'binary' ||
+    response.dynamicContentType !== true ||
+    typeof response.contentTypePattern !== 'string' ||
+    !response.contentTypePattern.trim() ||
+    typeof response.contentTypeSource !== 'string' ||
+    !response.contentTypeSource.trim()
+  ) {
+    return false;
+  }
+  try {
+    new RegExp(response.contentTypePattern);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const hasValidJsonResponseSchema = (response) => {
+  if (response.transport !== 'json' && response.transport !== 'webhook_ack') {
+    return true;
+  }
+  const schema =
+    response.envelope === 'systa_success_v1' ? response.dataSchema : response.bodySchema;
+  return isValidResponseJsonSchema(schema);
+};
+
+const hasValidBinaryMetadata = (response) => {
+  if (response.transport !== 'binary' || response.headers === undefined) {
+    return true;
+  }
+  return (
+    isPlainObject(response.headers) &&
+    (response.headers.contentDisposition === undefined ||
+      typeof response.headers.contentDisposition === 'string')
+  );
+};
+
+const hasValidBinaryDeliveryModes = (response) => {
+  if (response.deliveryModes === undefined) {
+    return true;
+  }
+  return (
+    response.transport === 'binary' &&
+    Array.isArray(response.deliveryModes) &&
+    response.deliveryModes.length > 0 &&
+    new Set(response.deliveryModes).size === response.deliveryModes.length &&
+    response.deliveryModes.every((mode) => RESPONSE_BINARY_DELIVERY_MODES.has(mode))
+  );
+};
+
+const hasValidRedirectMetadata = (response) =>
+  response.transport !== 'redirect' ||
+  (typeof response.locationSource === 'string' && Boolean(response.locationSource.trim()));
+
+const hasValidSseEvents = (response) =>
+  response.transport !== 'sse' ||
+  (Array.isArray(response.events) &&
+    response.events.length > 0 &&
+    response.events.every(
+      (event) =>
+        isPlainObject(event) &&
+        typeof event.name === 'string' &&
+        Boolean(event.name.trim()) &&
+        isValidResponseJsonSchema(event.dataSchema),
+    ));
+
+const isValidResponseVariant = (response) =>
+  hasValidResponseBasics(response) &&
+  hasValidResponseContentType(response) &&
+  hasValidDynamicContentType(response) &&
+  hasValidJsonResponseSchema(response) &&
+  hasValidBinaryMetadata(response) &&
+  hasValidBinaryDeliveryModes(response) &&
+  hasValidRedirectMetadata(response) &&
+  hasValidSseEvents(response);
+
+const isResponseContractV2 = (contract) => {
+  if (
+    !isPlainObject(contract) ||
+    contract.contractVersion !== 2 ||
+    !Array.isArray(contract.responses) ||
+    contract.responses.length === 0 ||
+    !contract.responses.every(isValidResponseVariant)
+  ) {
+    return false;
+  }
+  if (contract.errors === undefined) {
+    return true;
+  }
+  if (!isPlainObject(contract.errors) || !RESPONSE_ENVELOPES.has(contract.errors.envelope)) {
+    return false;
+  }
+  return (
+    contract.errors.statuses === undefined ||
+    (Array.isArray(contract.errors.statuses) &&
+      contract.errors.statuses.every(
+        (status) => Number.isInteger(status) && status >= 400 && status <= 599,
+      ))
+  );
+};
+
+const findCapabilityMethod = (caps, targetPath, targetMethod) => {
+  for (const module of caps.modules || []) {
+    const endpoint = (module.endpoints || []).find((item) => item.path === targetPath);
+    const method =
+      endpoint && (endpoint.methods || []).find((item) => item.method === targetMethod);
+    if (endpoint && method) {
+      return { module, endpoint, method };
+    }
+  }
+  return null;
+};
+
+const responseContractProblem = (responseSchema, targetMethod, targetPath) => {
+  if (responseSchema && responseSchema.contractVersion !== 2) {
+    return `Unsupported response contract version for ${targetMethod} ${targetPath}`;
+  }
+  if (!isResponseContractV2(responseSchema)) {
+    return `Missing or invalid Response Contract v2 for ${targetMethod} ${targetPath}`;
+  }
+  return null;
+};
+
+const describeCapabilityEndpoint = async (args) => {
+  const targetPath = String(args.path || '');
+  const targetMethod = String(args.method || '').toUpperCase();
+  const res = await systaFetch(
+    'GET',
+    capabilityProjectionPath('endpoint', { path: targetPath, method: targetMethod }),
+  );
+  if (!res.ok) {
+    return res;
+  }
+  const found = findCapabilityMethod(unwrapCapabilities(res), targetPath, targetMethod);
+  if (!found) {
+    return {
+      ok: false,
+      error: `Endpoint not found or not permitted for this key: ${targetMethod} ${targetPath}`,
+    };
+  }
+  const contractProblem = responseContractProblem(
+    found.method.responseSchema,
+    targetMethod,
+    targetPath,
+  );
+  if (contractProblem) {
+    return { ok: false, error: contractProblem };
+  }
+  const { responseSchema, ...methodDetail } = found.method;
+  return {
+    module: found.module.module,
+    path: found.endpoint.path,
+    summary: found.endpoint.summary,
+    ...methodDetail,
+    responseContract: responseSchema,
+    responseContractStatus: 'verified',
+  };
+};
+
 /**
  * Compact view of the capability catalog — drops field_schema/detail/scenario so
  * the per-turn payload stays small (lazy: use describe_endpoint for full detail).
@@ -433,7 +747,8 @@ const shapeCompact = (caps) => ({
         method: mm.method,
         safetyClass: mm.safetyClass,
         requiredPermission: mm.requiredPermission,
-        hasFields: Boolean(mm.fields),
+        hasFields: Boolean(mm.hasFields || mm.fields),
+        hasResponseContract: Boolean(mm.hasResponseContract || mm.responseSchema),
       })),
     })),
   })),
@@ -457,11 +772,16 @@ const shapeSummary = (caps) => ({
   moduleCount: caps.moduleCount,
   endpointCount: caps.endpointCount,
   hint: 'Summary view — endpoints omitted. Call list_capabilities({module:"<name>"}) or describe_module to see a module\'s endpoints.',
-  modules: (caps.modules || []).map((m) => ({
-    module: m.module,
-    ...(m.description ? { description: m.description } : {}),
-    endpointCount: (m.endpoints || []).length,
-  })),
+  modules: (caps.modules || []).map((m) => {
+    const paths = m.endpoints || [];
+    const methodCount = paths.reduce((sum, endpoint) => sum + (endpoint.methods || []).length, 0);
+    return {
+      module: m.module,
+      ...(m.description ? { description: m.description } : {}),
+      pathCount: m.pathCount ?? paths.length,
+      endpointCount: m.endpointCount ?? (methodCount || paths.length),
+    };
+  }),
 });
 
 const shapeOneModule = (caps, target) => {
@@ -3158,7 +3478,13 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       },
     },
     handler: async (args) => {
-      const res = await systaFetch('GET', '/api-keys/me/capabilities');
+      let projectionPath = capabilityProjectionPath('compact');
+      if (args && args.module) {
+        projectionPath = capabilityProjectionPath('module', { module: args.module });
+      } else if (args && args.summary) {
+        projectionPath = capabilityProjectionPath('summary');
+      }
+      const res = await systaFetch('GET', projectionPath);
       if (!res.ok) {
         return res;
       }
@@ -3176,7 +3502,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
     name: 'describe_module',
     description:
       'Orient on ONE SysTa module: returns its purpose (description, TR/EN), key concepts, ' +
-      'and the endpoints THIS key can call within it (path + summary + method/safety). Use the ' +
+      'the endpoints THIS key can call within it (path + summary + method/safety), and entryPoints — the calls that need NO id up front, i.e. where a chain starts. Use the ' +
       'module name from list_capabilities (e.g. "request", "kanban", "plan", "sla"). Helps map a ' +
       "user's natural-language intent to the right module before describe_endpoint.",
     inputSchema: {
@@ -3188,7 +3514,10 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       },
     },
     handler: async (args) => {
-      const res = await systaFetch('GET', '/api-keys/me/capabilities');
+      const res = await systaFetch(
+        'GET',
+        capabilityProjectionPath('module', { module: args.module }),
+      );
       if (!res.ok) {
         return res;
       }
@@ -3206,6 +3535,9 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
         module: mod.module,
         description: mod.description,
         concepts: mod.concepts,
+        // Zincirin BASI: kimlik gerektirmeyen uclar. Kullanicinin niyeti bu module
+        // dustuyse ilk cagri bunlardan biridir; donen kimlikler sonraki adimlari besler.
+        entryPoints: mod.entryPoints,
         endpoints: (mod.endpoints || []).map((e) => ({
           path: e.path,
           summary: e.summary,
@@ -3213,6 +3545,8 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
             method: mm.method,
             safetyClass: mm.safetyClass,
             requiredPermission: mm.requiredPermission,
+            // true ise once describe_endpoint ile onkosullari oku.
+            hasPrerequisites: mm.hasPrerequisites,
           })),
         })),
       };
@@ -3221,14 +3555,14 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
   {
     name: 'describe_endpoint',
     description:
-      'Get full detail for one capability: input field types (fields), response shape ' +
-      '(responseSchema — the data body inside the {success, data} envelope), safety class, ' +
-      'required permission, and summary/scenario when available. Use the path + method from ' +
+      'Get full detail for one capability: input field types (fields), full HTTP Response ' +
+      'Contract v2 (status, transport, content type, envelope and data/body schema), safety class, ' +
+      'required permission, prerequisites (which id this call needs FIRST and which endpoint produces it), and summary/scenario when available. Use the path + method from ' +
       'list_capabilities. Returns only if the key is permitted to call it.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
-      required: ['path'],
+      required: ['path', 'method'],
       properties: {
         path: {
           type: 'string',
@@ -3237,41 +3571,11 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
         method: {
           type: 'string',
           enum: ALLOWED_METHODS,
-          description: 'Optional HTTP method to disambiguate',
+          description: 'HTTP method; required so multi-method paths are never selected ambiguously',
         },
       },
     },
-    handler: async (args) => {
-      const targetPath = String(args.path || '');
-      const targetMethod = args.method ? String(args.method).toUpperCase() : '';
-      const res = await systaFetch('GET', '/api-keys/me/capabilities');
-      if (!res.ok) {
-        return res;
-      }
-      const caps = unwrapCapabilities(res);
-      for (const module of caps.modules || []) {
-        for (const endpoint of module.endpoints || []) {
-          if (endpoint.path !== targetPath) {
-            continue;
-          }
-          const match = (endpoint.methods || []).find(
-            (mm) => !targetMethod || mm.method === targetMethod,
-          );
-          if (match) {
-            return {
-              module: module.module,
-              path: endpoint.path,
-              summary: endpoint.summary,
-              ...match,
-            };
-          }
-        }
-      }
-      return {
-        ok: false,
-        error: `Endpoint not found or not permitted for this key: ${targetMethod || 'ANY'} ${targetPath}`,
-      };
-    },
+    handler: describeCapabilityEndpoint,
   },
 
   // ══════════════════════════════════════════════════════════════════════════
@@ -4180,7 +4484,7 @@ let allowedPermissionsPromise = null;
 // bir kez cekilir (memoized). Basarisizlik -> null (cagiran fail-open/closed'a karar verir).
 const fetchAllowedPermissions = async () => {
   try {
-    const res = await systaFetch('GET', '/api-keys/me/capabilities');
+    const res = await systaFetch('GET', capabilityProjectionPath('compact'));
     if (!res || !res.ok) {
       return null;
     }
@@ -4447,6 +4751,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  INSTRUCTIONS,
   TOOLS,
   TOOL_MAP,
   TOOL_REQUIRED_PERMISSION,