systa-mcp 1.5.0 → 1.8.0

package/README.md

@@ -101,7 +101,7 @@ claude mcp add systa \
 
 ## Araçlar (tools)
 
-Toplam **79 araç** vardır; `tools/list` yanıtı anahtarın kapsamına göre filtrelenir
+Toplam **90 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.
 
@@ -119,6 +119,33 @@ tam katalog `list_capabilities` ile keşfedilir.
 | `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, güvenlik sınıfı ve tam HTTP Response Contract v2 — çağrı gövdesini kurmadan ve yanıtı zincirlemeden önce                                                                                            |
 
+### Agent koordinasyonu (çalışma oturumu ve sohbet)
+
+İki agent aynı kayıtta habersiz çalışırsa birbirinin işini ezer. Bu araçlar tam olarak
+onu önler. Sıra: **bak → konuş → sahiplen → sinyal ver → bırak.**
+
+| Araç                          | Açıklama                                                                                  |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| `list_active_work_sessions`   | Şu anda kim neyin üzerinde çalışıyor — düzenlemeden ÖNCE bak — `work-session.view-active` |
+| `start_work_session`          | Kaydı sahiplen (talep ya da kart, tam biri); nota YERİNİ yaz — `work-session.manage`      |
+| `send_work_session_heartbeat` | Çalışırken sinyal ver; 15 dakika sessizlik oturumu kapatır — `work-session.manage`        |
+| `update_work_session_note`    | Yer değiştirdiysen notu tazele (`null` notu siler) — `work-session.manage`                |
+| `end_work_session`            | İddiayı bırak; gövde göndermek gerekmez — `work-session.manage`                           |
+| `list_my_work_sessions`       | Kendi açık oturumların — `work-session.manage`                                            |
+| `list_work_session_history`   | Bir kaydın geçmiş oturumları (imleç geriye gider) — `work-session.view-active`            |
+| `send_work_session_message`   | Birinin açık oturumuna yaz (kapalı oturum 409 döner) — `collaboration.message`            |
+| `send_room_message`           | Kaydın kendisine kalıcı not: `project` / `request` / `card` — `collaboration.message`     |
+| `read_messages`               | Konuşmayı oku; `afterId` ile "son okuduğumdan beri ne geldi"                              |
+| `listen_room`                 | Sınırlı süre canlı dinle (varsayılan 30 sn, en çok 120) — `work-session.view-active`      |
+
+**Odaya katılma diye bir adım yoktur.** Oda abone olunan kanal değil, kaydın kendisidir;
+erişim kapsamın yetiyorsa okur ve yazarsın. Gantt ve k&k chart üzerindeki düğüm proje,
+talep ya da kart olabilir — mesaj düğümün **temsil ettiği şeyin** odasına gider.
+
+**Sürekli dinleme (monitor) kipi yoktur.** MCP istemcisine push gelmez. Bekliyorsan
+`listen_room`, çalışıyorsan uğrayış başına tek `read_messages(afterId)`. İkisini birden
+yapmak ya da `listen_room` çağrılarını zincirlemek turu boşa harcar.
+
 `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.
@@ -226,3 +253,9 @@ npm publish            # publishConfig.access=public ile public yayınlanır
 ```
 
 Sürüm `package.json` ve `server.js` (`SERVER_VERSION`) içinde **birlikte** yükseltilir.
+
+### Yayınlanmamış değişiklikler (sonraki yayına girer)
+
+- `resolve_user_by_name` çıktısı `list_users` ile aynı nested şekli ilan eder: `company{id,name}`,
+  `department{id,name}` (eski düz `companyName`/`departmentName` kaldırıldı — Faz 33).
+- SKILL.md: `stakeHolders` → `stakeholders` (tek yazım; arka uç `stakeHolders` kabul etmez).

package/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 1.5.0
+version: 1.8.0
 name: systa
 description: |
   Drive SysTa (Talep Takip Sistemi / SysTa) — a
@@ -79,7 +79,7 @@ Short shared vocabulary. Use these words with the user; never expose raw REST pa
 | --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Talep                 | Request / ticket    | Core unit of work. Has `title` (min 5), `companyId`, `statusId`, priority, category, assignee, comments, files, relations. Çoğu iş bir talebin etrafında döner. |
 | Durum                 | Status              | Lifecycle state (Açık/Open, Devam Ediyor/In Progress, Tamamlandı/Done). `is_final` durumlar kapanışı temsil eder. Resolved via `GET /api/statuses`.             |
-| Öncelik               | Priority            | normal / high / critical. Belirtilmezse `normal`.                                                                                                               |
+| Öncelik               | Priority            | low / normal / high / urgent / critical. Belirtilmezse `normal`.                                                                                                |
 | Kategori              | Category            | Talep sınıflandırması (catalog/config).                                                                                                                         |
 | Yorum                 | Comment             | Talebe eklenen not/yorum (`commentText` plain string ok).                                                                                                       |
 | Atama                 | Assignment          | `assignedTo` = bir kullanıcı. "bana/üzerime" → mevcut `userId`.                                                                                                 |
@@ -163,6 +163,7 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 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.
+8. **Write bodies are NESTED (raw `systa_api_call` POST/PUT/PATCH).** Identity references go as groups, exactly as `describe_endpoint(...).fields` shows: `{ "status": { "id": 9 }, "company": { "id": 12 }, "priority": { "key": "high" }, "project": null }` — never flat `statusId`/`companyId` (transitional, will be rejected). `null` on a group clears the link. GET query/filter keys stay flat (`statusId=9`). Named tools (`create_request`, `update_request`, `change_request_status`, `bulk_update_requests`, `create_project`, `update_project`, `create_release_list`, `add_release_item`, `log_effort`, `update_effort_entry`, `request_approval`) take flat args and convert for you.
 
 ## Discovery
 
@@ -200,6 +201,54 @@ So the flow is: **user intent → `list_capabilities` (module) → `describe_mod
 
 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.
 
+### Aynı iş üzerinde çakışmamak (agent koordinasyonu) — `list_active_work_sessions` → mesajlaşma
+
+**Bir talebi ya da görev kartını düzenlemeden ÖNCE bu akışı işlet.** İki agentin habersiz aynı dosyada çalışması, çakışan değişiklik ve tekrar eden iş üretir; bu araçlar tam olarak onu önlemek için var.
+
+1. **Bak.** `list_active_work_sessions` — o kayıtta çalışan var mı? Her satır kişiyi, hedefi (talep ya da kart), başlangıcı, son canlılık sinyalini ve kişinin bıraktığı **serbest notu** taşır. En değerli alan nottur: "src/models/foo.js içindeyim" gibi. Karar vermeden önce onu oku. Bir oturum durdurulana ya da on beş dakika sessiz kalana kadar listede durur, yani listelenen oturum canlı bir iddiadır.
+2. **Konuş.** Çakışma varsa `send_work_session_message(sessionId, body)` ile o kişiye yaz. İşe yarayan cümleler somut olanlardır: "src/models/foo.js bende, controller sende", "1042 migration'ını sen indirene kadar bekliyorum", "API sözleşmem `POST /api/x -> {id}`, buna göre devam edebilirsin".
+3. **Başla.** `start_work_session(requestId | cardId, description)` ile kendi oturumunu aç. Hedef olarak **tam biri** verilir; ikisi birden ya da hiçbiri `EXACTLY_ONE_TARGET` ile reddedilir. `cardId` kartın **genel** kimliğidir (`get_request_board` içindeki `card.id`), pano içindeki "#3" sırası değildir. Nota niyet değil **yer** yaz: "src/models/request/requestCrudModel.js, create yolu" cümlesi "talep üzerinde çalışıyorum" cümlesinden çok daha işe yarar; çünkü senden sonra gelen agent kararını o nota bakarak verir.
+4. **Çalışırken sinyal ver.** `send_work_session_heartbeat(sessionId)`. On beş dakika sessiz kalan oturum otomatik kapanır ve sen hâlâ dosyadayken iddian düşer. MCP çağrıları kendiliğinden sinyal sayılmaz: uzun bir derleme, test koşusu ya da büyük bir refactor sırasında adımlar arasında bunu çağır. Otomatik kapanışta bitiş zamanı **son sinyal anı** yazılır, kapanma anı değil; yani terk edilmiş oturum kimsenin eforunu şişirmez.
+5. **Notunu güncel tut.** Yer değiştirdiysen `update_work_session_note(sessionId, description)`. Model katmanını alıp controller'a geçtiysen eski not, senden kaçınmaya çalışan agenti tam da girdiğin dosyaya yollar. `description: null` notu tamamen siler, oturum açık kalır.
+6. **Bitince bırak.** `end_work_session(sessionId)`. "Bitti" demek görevi bitirmek değil, **oturmayı** bitirmektir: bir saatliğine ara vermek de bırakmaktır. Açık kalan oturum göstergeyi yalancı yapar ve sıradaki agenti boşuna bekletir. Gövde göndermene gerek yok; `endedAt` yalnız geçmişte olmuş bir durmayı kaydetmek için vardır.
+
+**Kendi oturumlarını bulmak.** `list_my_work_sessions` yalnız _senin_ açık oturumlarını verir; `sessionId`'yi kaybettiysen ya da daha önce kapatmayı unuttuğun bir iddia olup olmadığını merak ediyorsan buraya bak. Başkalarının canlı iddiaları için `list_active_work_sessions`, bir kaydın geçmişi için `list_work_session_history(requestId | cardId)` kullanılır; geçmiş yeniden eskiye sıralıdır, bu yüzden imleç **geriye** gider (`beforeId`).
+
+**Birini bulmak durmak demek değildir.** Aynı talepte farklı dosyalarda iki agent olması normaldir. Kabul edilmeyen şey, haber vermeden başlamaktır.
+
+**Hangi araç ne zaman.** Mesaj kişinin _o anki oturumuna_ aitse `send_work_session_message`; kaydın _kendisine_ ait kalıcı bir not ise `send_room_message`. "Şu an o dosyadayım" oturuma aittir; "migration numaralandırması 1042'den devam ediyor" odaya aittir. Oda mesajı oturumdan uzun yaşar ve sonra gelen okur.
+
+**Odaya "katılma" diye bir adım yoktur.** Oda abone olunan bir kanal değil, kaydın kendisidir. Erişim kapsamın o projeyi, talebi ya da kartı görmene izin veriyorsa odasını da okur ve yazarsın: oluşturulacak bir şey, katılma çağrısı, üyelik kaydı yoktur. Kapsam dışı bir oda boş küme değil doğrudan ret döner; yani ret "senin değil" demektir, "yok" demek değil.
+
+**Hangi ekran hangi oda.** İnsan senin mesajını kaydın kendi ekranında görür, o yüzden odayı konuşmanın ait olduğu yere göre seç:
+
+| roomType  | roomId               | Kullanicinin gordugu yer                                                 |
+| --------- | -------------------- | ------------------------------------------------------------------------ |
+| `request` | talep numarasi       | Talep detay ekranindaki sohbet                                           |
+| `card`    | kartin GENEL kimligi | Gorev kartinin sohbeti (`card.id`, pano ici "#3" degil)                  |
+| `project` | proje kimligi        | Proje sohbeti; Gantt ve k&k chart proje dugumune tiklandiginda bunu acar |
+
+Gantt ve k&k chart üzerinde bir düğüm proje, talep ya da kart olabilir. Mesajı **düğümün temsil ettiği şeyin** odasına gönder: tek bir talebi ilgilendiren not, okuyucu grafiğe bakıyor diye proje odasına ait olmaz.
+
+**Yeni mesajı nasıl alırsın: iki yol var, ikisini birden yapma.**
+
+Önce şunu bil: MCP istemcisine **push yoktur**. Arka planda çalışan bir abonelik, seni uyandıran bir olay yoktur. Ya beklersin ya dönüp sorarsın.
+
+1. **Bekliyorsan → `listen_room(roomType, roomId, seconds)`.** Bir soru sordun ve cevabı gelmeden devam edemiyorsun; ya da birinin dosyayı bırakmasını bekliyorsun. `listen_room` canlı kanalı açar, **sınırlı süre** bekler (varsayılan 30 saniye, en çok 120) ve o sırada geleni döndürür. `stoppedBy` neden döndüğünü söyler: `timeout` | `maxEvents` | `streamEnded`. Beklemeye devam etmek için yeniden çağırırsın.
+2. **Çalışıyorsan → `read_messages(..., afterId)`.** Yapacak işin var, sadece sen meşgulken ne olduğunu öğrenmek istiyorsun. Her uğrayışta **tek çağrı**, döngü değil. Uğrayışlar arasında asıl işini yap.
+
+**Sürekli dinleme (monitor) diye bir kip yoktur.** `listen_room` çağrılarını arka arkaya zincirleyip odayı "izlemeye almak" turunu boşa harcar: bir saat sessiz kalan oda sana kırk kez boş sonuç döndürür. Aynı şekilde `read_messages`'ı sıkı döngüde çağırmak da yanlış cevaptır. Doğru soru şudur: **şu an bekliyor muyum, yoksa çalışıyor muyum?**
+
+**İmleç.** `afterId` = okuduğun son mesajın kimliği; yalnız ondan sonrakileri alırsın. **Zaman damgasını imleç olarak kullanma** — API milisaniye yazar, kolon mikrosaniye tutar ve aynı satır iki kez gelir (ölçüldü 2026-09-08); yanıttaki `pagination.nextAfterId` alanını kullan. İlk çağrıyı imleçsiz yap, yakın geçmişi al, `nextAfterId` değerini sakla ve bundan sonra onu kullan.
+
+**Hiçbir yolda mesaj kaybolmaz.** Olaylar `read_messages` ile aynı biçimi taşır, ayrı bir çözümleme gerekmez. Akış koparsa `read_messages(afterId = gördüğün son id)` ile tam kaldığın yerden devam edersin. Canlılık sinyalleri taşıma katmanına aittir ve olay olarak görünmez; yani boş sonuç gerçekten "kimse bir şey söylemedi" demektir.
+
+**Oturum konuşması oturumla biter.** Yarın yeniden çalışmaya başlamak **yeni** bir konuşma açar, dünkü satırlar geri gelmez. Oda konuşması ise kalıcıdır ve her oturumdan uzun yaşar. Kalıcı olması gereken not odaya yazılır.
+
+**Yetkiler ayrıdır.** Görmek `work-session.view-active`, yazmak `collaboration.message` ister. Koordinasyonu izleyip katılmayan bir rol meşru bir yapılandırmadır; yazma izni yoksa uç boş küme değil doğrudan yetki hatası döner ve hangi iznin gerektiğini söyler.
+
+**Kapanmış oturuma yazılmaz.** `WORK_SESSION_ENDED` (409) tekrar denenecek bir hata değildir: kişi çalışmayı bırakmıştır. Ya kaydı oku ya kendi oturumunu aç.
+
 ### Talep aç (open a request) — `create_request` → `POST /api/requests`
 
 1. Need `title` (min 5 chars) — if missing or too short, ask once. Never invent it.
@@ -209,7 +258,7 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 
 ### Üzerimdeki işler / talepleri listele (what's on my plate) — `list_requests` → `GET /api/requests`
 
-- "taleplerim / on me" → `assignedTo=<my userId>`. "açık/open" → `openOnly:true`. "geciken/overdue" → `overdue:true` (deadline geçmiş + non-final auto-composed) veya `slaBreached:true` (SLA ihlali). "SLA durumu" → `slaStatus:['breached','active']`. **"dosyalı talepler / eki olan" → `hasAttachments:true`** (top-level talep eki). Deadline'a göre → `deadlineFrom`/`deadlineTo` (YYYY-MM-DD) ya da `deadlineWithinDays:N` (önümüzdeki N gün). Search kapsamını genişlet: `searchIn:['assignee','creator','comments',...]`. **Response boyutu:** `fields` varsayılan `'summary'` (satır başına ~1KB); `'detail'` (description/effort/counts eklenir) veya `'full'` (customFields/stakeHolders dahil, çok büyük). Default `limit=20-50`, sort `created_at desc`. Yanıt zarfı: `{items, total, limit, offset}` — sayfa sayısı `= ceil(total/limit)`. Summarize as a short list (numara + başlık + durum), not raw rows.
+- "taleplerim / on me" → `assignedTo=<my userId>`. "açık/open" → `openOnly:true`. "geciken/overdue" → `overdue:true` (deadline geçmiş + non-final auto-composed) veya `slaBreached:true` (SLA ihlali). "SLA durumu" → `slaStatus:['breached','active']`. **"dosyalı talepler / eki olan" → `hasAttachments:true`** (top-level talep eki). Deadline'a göre → `deadlineFrom`/`deadlineTo` (YYYY-MM-DD) ya da `deadlineWithinDays:N` (önümüzdeki N gün). **`overdue` ile `deadlineWithinDays` birlikte kullanılmaz** — ikisi aynı arka uç parametresine yazar, birlikte verilirse `overdue` kazanır ve diğeri sessizce yok sayılır (zaten ters soruları sorarlar: geçmiş vs. yaklaşan). Search kapsamını genişlet: `searchIn:['assignee','creator','comments',...]`. **Response boyutu:** `fields` varsayılan `'summary'` (satır başına ~1KB); `'detail'` (description/effort/counts eklenir) veya `'full'` (customFields/stakeholders dahil, çok büyük). Default `limit=20-50`, sort `created_at desc`. Yanıt zarfı: `data.items[]` + `data.pagination{total, limit, offset, page, totalPages}` — dizinin anahtarı `items`'tır ve ikisi de `data` altındadır (canlı ölçüldü 2026-09-05). Summarize as a short list (numara + başlık + durum), not raw rows.
 
 ### Talep detayı (show a request) — `get_request` → `GET /api/requests/:requestNumber`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systa-mcp",
-  "version": "1.5.0",
+  "version": "1.8.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

@@ -44,7 +44,7 @@ const INSTRUCTIONS = [
   'cagri yine de sunucu tarafinda 403 doner. Bir isi yapmadan ONCE:',
   '  1) `list_capabilities` cagir — anahtarin erisebildigi modul/endpoint katalogunu',
   '     (scope-filtreli) gorursun. GENIS/WILDCARD anahtarda ONCE `list_capabilities({summary:true})`',
-  '     cagir (oryantasyon + modul indeksi, birkac KB; tam katalog yuzlerce KB olabilir), sonra',
+  '     cagir (oryantasyon + modul indeksi, ~57 KB; compact katalog ~483 KB, projeksiyonsuz cagri megabaytlara cikar), sonra',
   '     ilgili modul icin `list_capabilities({module:"<ad>"})` ile derinles. Yetkisiz endpoint listede GORUNMEZ. Yanit AYRICA SysTa',
   '     platform OZETI (overview), TR GLOSSARY, her modulun ACIKLAMASINI (description/concepts)',
   '     ve SENIN kullanicini (user) icerir — "ben / bana ata / uzerimdeki" niyetinde assignedTo',
@@ -199,6 +199,19 @@ const logErr = (message) => process.stderr.write(`[${SERVER_NAME}] ${message}\n`
  * @param {{query?:Object, body?:*}} [opts]
  * @returns {Promise<{status:number, ok:boolean, data:*}>}
  */
+/**
+ * Nested grup atfi (`{id, name}`): API'nin dondurdugu grubu aynen gecirir,
+ * yoksa `null`. MCP araclari ayni kavrami TEK sekilde ilan eder (Faz 33):
+ * `list_users` API satirini oldugu gibi verir, `resolve_user_by_name` de bu
+ * yardimci ile ayni grubu verir.
+ */
+function kullaniciGrubu(grup) {
+  if (!grup || typeof grup !== 'object') {
+    return null;
+  }
+  return { id: grup.id ?? null, name: grup.name ?? null };
+}
+
 const systaFetch = async (method, path, opts = {}) => {
   if (!BASE_URL) {
     throw new Error('SYSTA_API_BASE_URL is not configured');
@@ -383,6 +396,125 @@ const systaFetchBinary = async (apiPath) => {
   };
 };
 
+/**
+ * SSE akisini SINIRLI bir sure dinler ve toplanan olaylari dondurur.
+ *
+ * MCP araclari istek/yanit calisir; sonsuz bir akis dondurulemez. Bu yuzden
+ * dinleme "su kadar saniye dinle, ne geldiyse ver" seklindedir. Agent bir isi
+ * beklerken bunu cagirir, dondugunde ya olaylari alir ya da bos donerek "bu
+ * surede bir sey olmadi" bilgisini alir.
+ *
+ * SIFIR BAGIMLILIK: Node'un yerlesik fetch'i yanit govdesini akitir, EventSource
+ * kutuphanesi gerekmez. Zaten SSE'nin socket yerine secilme sebebi de buydu.
+ *
+ * Kalp atisi satirlari (`:` ile baslayan yorumlar) olay DEGILDIR ve atlanir;
+ * baglantinin canli oldugunu gosterirler.
+ */
+/**
+ * Tek bir SSE kaydini (bos satirla ayrilmis blok) olaya cevirir.
+ *
+ * Kalp atisi satirlari (`:` ile baslayan yorumlar) olay DEGILDIR ve atlanir;
+ * baglantinin canli oldugunu gosterirler. `data:` satiri yoksa kayit bir olay
+ * tasimiyordur ve `null` doner.
+ */
+const parseSseRecord = (raw) => {
+  let eventName = 'message';
+  const dataLines = [];
+  for (const line of raw.split('\n')) {
+    if (line.startsWith(':')) {
+      continue;
+    }
+    if (line.startsWith('event:')) {
+      eventName = line.slice(6).trim();
+    } else if (line.startsWith('data:')) {
+      dataLines.push(line.slice(5).trim());
+    }
+  }
+  if (dataLines.length === 0) {
+    return null;
+  }
+  const text = dataLines.join('\n');
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    payload = text;
+  }
+  return { event: eventName, data: payload };
+};
+
+/**
+ * SSE akisini SINIRLI bir sure dinler ve toplanan olaylari dondurur.
+ *
+ * MCP araclari istek/yanit calisir; sonsuz bir akis dondurulemez. Bu yuzden
+ * dinleme "su kadar saniye dinle, ne geldiyse ver" seklindedir. Agent bir isi
+ * beklerken bunu cagirir; dondugunde ya olaylari alir ya da bos donerek "bu
+ * surede bir sey olmadi" bilgisini alir.
+ *
+ * SIFIR BAGIMLILIK: Node'un yerlesik fetch'i yanit govdesini akitir, EventSource
+ * kutuphanesi gerekmez. Zaten SSE'nin soket yerine secilme sebebi de buydu.
+ */
+const systaStream = async (apiPath, { seconds = 30, maxEvents = 50 } = {}) => {
+  if (!BASE_URL) {
+    throw new Error('SYSTA_API_BASE_URL is not configured');
+  }
+  if (!API_KEY) {
+    throw new Error('SYSTA_API_KEY is not configured');
+  }
+  const headers = { Authorization: `Bearer ${API_KEY}`, Accept: 'text/event-stream' };
+  if (VENDOR_CODE) {
+    headers['X-Vendor-Code'] = VENDOR_CODE;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1, seconds) * 1000);
+  const events = [];
+  try {
+    const response = await fetch(new URL(BASE_URL + apiPath), {
+      method: 'GET',
+      headers,
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      let data;
+      try {
+        data = text ? JSON.parse(text) : null;
+      } catch {
+        data = text;
+      }
+      return { status: response.status, ok: false, data };
+    }
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for await (const chunk of response.body) {
+      buffer += decoder.decode(chunk, { stream: true });
+      // SSE kayitlari BOS SATIRLA ayrilir; yarim kalan son parca tamponda kalir.
+      let index = buffer.indexOf('\n\n');
+      while (index !== -1) {
+        const event = parseSseRecord(buffer.slice(0, index));
+        buffer = buffer.slice(index + 2);
+        if (event !== null) {
+          events.push(event);
+        }
+        if (events.length >= maxEvents) {
+          controller.abort();
+          return { status: 200, ok: true, data: { events, stoppedBy: 'maxEvents' } };
+        }
+        index = buffer.indexOf('\n\n');
+      }
+    }
+    return { status: 200, ok: true, data: { events, stoppedBy: 'streamEnded' } };
+  } catch (error) {
+    // Sure dolunca akisi BIZ kesiyoruz; bu bir hata degil, beklenen son.
+    if (error.name === 'AbortError') {
+      return { status: 200, ok: true, data: { events, stoppedBy: 'timeout' } };
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
 /** Multipart yukleme — native FormData/Blob (Node 18+), alan adi backend'le ayni: 'file'. */
 const systaUploadMultipart = async (apiPath, method, filePaths) => {
   if (!BASE_URL) {
@@ -434,6 +566,136 @@ const capabilityProjectionPath = (projection, filters = {}) => {
   return `/api-keys/me/capabilities?${query.toString()}`;
 };
 
+/**
+ * ═══ NESTED YAZMA GOVDESI (karar 6.2 / Faz 21 / BF-92) ═══
+ *
+ * API sozlesmesi okumada da yazmada da nested'dir: `PUT /requests/:n` govdesi
+ * `{ status: { id: 9 } }` tasir, `{ statusId: 9 }` degil. Arac girdileri (AI
+ * ajaninin verdigi args) DUZ kalir — `statusId`, `companyId` ajan icin dogal
+ * anahtarlardir ve `prepare_create_request` bu adlarla id dondurur; donusum
+ * yalniz tel govdesine yazilirken burada yapilir. Duz kabul sunucuda
+ * KAPANACAKTIR; bu yardimci olmadan gonderilen govde o zaman 400 alir.
+ *
+ * Bu paket bagimsiz yayinlanir (npm systa-mcp), arka uc `fieldGroupSpec`i
+ * import edemez; harita KOPYADIR ve `tests/mcp-server/server.test.js`
+ * spec-sync testiyle arka uca kilitlidir.
+ */
+// Yalniz MCP'nin yazdigi iki varligin (talep, proje) gruplari; kullanici/takim
+// araclari eklenirse harita ve YAZMA_GRUPLARI birlikte buyur (spec-sync testi).
+const YAZMA_YOLLARI = Object.freeze({
+  statusId: ['status', 'id'],
+  // Onay kaydinin gidecegi/geldigi durum atiflari (Faz 29 okuma sozlesmesi);
+  // FE `nestedWriteBody` ile ayni yollar.
+  pendingStatusId: ['pendingStatus', 'id'],
+  previousStatusId: ['previousStatus', 'id'],
+  categoryId: ['category', 'id'],
+  priority: ['priority', 'key'],
+  companyId: ['company', 'id'],
+  departmentId: ['department', 'id'],
+  organizationId: ['organization', 'id'],
+  subOrganizationId: ['subOrganization', 'id'],
+  projectId: ['project', 'id'],
+  parentProjectId: ['parentProject', 'id'],
+  mainProjectId: ['mainProject', 'id'],
+  formId: ['form', 'id'],
+  formVersion: ['form', 'version'],
+  addToNextReleaseList: ['release', 'addToNext'],
+  targetReleaseListId: ['release', 'targetListId'],
+  // NOT: `slaId` yazma yolu YOK. Arka uc `sla` grubunun kimligi `definitionId`
+  // (`slaDefinitionId`); `slaId` yalnizca ES ANLAMLI eski addir. Harita
+  // `slaId -> sla.id` ilan ediyordu: hicbir arac bu argumani kabul etmiyordu
+  // (olu yol) ve kabul etseydi arka ucun tanimadigi bir grup uretecekti.
+  // Spec-sync kapisi bunu yakaliyordu (HEAD'de KIRMIZI, 2026-09-05).
+  // Faz 22 — surum, efor, SLA tanimi, onay
+  requestId: ['request', 'id'],
+  activityTypeId: ['activityType', 'id'],
+});
+
+/** Varlik basina nested yazilan gruplar — arka uc ENTITY_GROUPS ile ayni. */
+const YAZMA_GRUPLARI = Object.freeze({
+  // SIRA ve UYELIK arka uctaki `ENTITY_GROUPS.request_entity` ile BIREBIR
+  // aynidir (spec-sync kapisi). `team` buradaydi ama talep yazma sozlesmesinde
+  // YOKTU: hicbir arac `teamId` argumani almiyordu ve alsaydi arka ucun
+  // tanimadigi bir grup uretecekti (olu yol, 2026-09-05). `subOrganization`
+  // (mig 980) ise sozlesmede VARDI, haritada YOKTU.
+  request: [
+    'status',
+    'category',
+    'priority',
+    'company',
+    'department',
+    'organization',
+    'subOrganization',
+    'project',
+    'parentProject',
+    'mainProject',
+    'form',
+    'release',
+    'sla',
+  ],
+  project: [
+    'company',
+    'department',
+    'organization',
+    'subOrganization',
+    'parentProject',
+    'mainProject',
+  ],
+  // Faz 22 — arac yazan aileler (okuma sozlesmesi nested olanlar)
+  release: ['company', 'category', 'department', 'organization', 'status', 'request'],
+  effort: ['category', 'project', 'request', 'activityType'],
+  slaDefinition: ['form', 'company', 'department', 'organization', 'subOrganization'],
+  approval: [
+    'request',
+    'status',
+    'category',
+    'priority',
+    'company',
+    'department',
+    'organization',
+    'subOrganization',
+    'project',
+    // Onay kaydinin bekleyen/onceki durumu (Faz 29): okuma sozlesmesinde grup,
+    // yazma haritasinda da ayni kapsam.
+    'pendingStatus',
+    'previousStatus',
+  ],
+});
+
+const COKLU_ALANLI_GRUPLAR = new Set(
+  Object.values(YAZMA_YOLLARI)
+    .map(([grup]) => grup)
+    .filter((grup, i, dizi) => dizi.indexOf(grup) !== i),
+);
+
+/**
+ * Duz anahtarli govdeyi varligin kapsamindaki gruplar icin nested'a cevirir.
+ * `null` = baglantiyi kaldir (tek alanli grupta grup null), `undefined` girmez.
+ * Kapsam disi anahtarlar (oz alanlar, `assignedTo`, `title`) aynen gecer.
+ */
+const toNestedWriteBody = (varlik, duz) => {
+  const kapsam = YAZMA_GRUPLARI[varlik] || [];
+  const sonuc = {};
+  const gruplar = {};
+  for (const [anahtar, deger] of Object.entries(duz || {})) {
+    const yol = YAZMA_YOLLARI[anahtar];
+    if (!yol || !kapsam.includes(yol[0])) {
+      sonuc[anahtar] = deger;
+      continue;
+    }
+    if (deger === undefined) {
+      continue;
+    }
+    const [grup, alan] = yol;
+    gruplar[grup] = { ...(gruplar[grup] || {}), [alan]: deger };
+  }
+  for (const [grup, nesne] of Object.entries(gruplar)) {
+    const hepsiNull = Object.values(nesne).every((v) => v === null);
+    sonuc[grup] = hepsiNull && !COKLU_ALANLI_GRUPLAR.has(grup) ? null : nesne;
+  }
+  return sonuc;
+};
+
 const RESPONSE_TRANSPORTS = new Set([
   'json',
   'binary',
@@ -757,8 +1019,9 @@ const shapeCompact = (caps) => ({
 /**
  * Index-only view: orientation (overview/glossary/user) + module names with
  * endpoint COUNTS, but NO per-endpoint detail. For a wildcard '*' key the full
- * compact catalog is ~250KB (26 modules / 698 endpoints) which overflows agent
- * buffers; this summary is a few KB. Drill into one module with module='x'.
+ * compact catalog is ~483KB (69 modules / 1663 endpoint-methods, olculdu 2026-08-30)
+ * which overflows agent buffers; this summary is ~57KB. Drill into one module with
+ * module='x' (~54KB) or straight to describe_endpoint (~22KB).
  */
 const shapeSummary = (caps) => ({
   sessionType: caps.sessionType,
@@ -872,7 +1135,11 @@ const resolveStatusIdByKeyForRequest = async (requestNumber, statusKey) => {
     () => null,
   );
   const reqData = reqRes?.data?.data?.request ?? reqRes?.data?.data ?? null;
-  const reqFormId = typeof reqData?.formId === 'number' ? reqData.formId : null;
+  // Talep detayi `form: {id, key, name, version}` grubunu doner (Faz 3+);
+  // duz `formId` artik YOK. Eski okuma her zaman null donuyor ve durumlar
+  // form suzgeci OLMADAN cekiliyordu -> yanlis durum kumesi (BF-55).
+  const formGrupId = reqData?.form?.id;
+  const reqFormId = typeof formGrupId === 'number' ? formGrupId : null;
   const statusesRes = await systaFetch('GET', '/statuses', {
     query: reqFormId != null ? { formId: reqFormId } : undefined,
   });
@@ -1093,7 +1360,7 @@ const MODULE_GATE_NOTE =
 const TOOLS = [
   {
     name: 'list_requests',
-    description: `List/search SysTa requests (talepler) with pagination and rich filters: status, assignee, company, category, department, priority, free-text, OVERDUE / SLA / DEADLINE. Common intents: 'uzerimdeki acik isler / my open work' => assignedTo=<me> + openOnly:true (excludes final statuses). 'geciken isler / overdue' => overdue:true (deadline gecmis + non-final) OR slaBreached:true (SLA ihlali). 'bu ay kapatilan' => finalOnly:true + completedFrom/completedTo (NOT YET SUPPORTED — use systa_api_call). search covers title/requestNumber/description/externalRef by default (NOT assignee/creator); use searchIn to expand. Multiple statuses: statusId can be an array [1,3,5]. Returns only requests the API key scope permits. Response envelope: {items:[], total, limit, offset} — totalPages = ceil(total/limit). RESPONSE SIZE: fields controls how much each row carries -- default 'summary' returns lightweight rows (~1KB each: id, requestNumber, title, statusName, priority, assignedTo, deadline, isOverdue, slaStatus, commentCount, fileCount). Use fields:'detail' when you need description/effort/counts, or fields:'full' for everything incl. customFields/stakeHolders (LARGE — S-A2 kanit: 44 talep tam moduyla ~300KB).${MASKING_NOTE}${EMPTY_SCOPE_NOTE}`,
+    description: `List/search SysTa requests (talepler) with pagination and rich filters: status, assignee, company, category, department, priority, free-text, OVERDUE / SLA / DEADLINE. Common intents: 'uzerimdeki acik isler / my open work' => assignedTo=<me> + openOnly:true (excludes final statuses). 'geciken isler / overdue' => overdue:true (deadline gecmis + non-final) OR slaBreached:true (SLA ihlali). 'bu ay kapatilan' => finalOnly:true + completedFrom/completedTo (NOT YET SUPPORTED — use systa_api_call). search covers title/requestNumber/description/externalRef by default (NOT assignee/creator); use searchIn to expand. Multiple statuses: statusId can be an array [1,3,5]. Returns only requests the API key scope permits. Response envelope: data.items[] + data.pagination{total,limit,offset,page,totalPages} — the array key is 'items' and both live under 'data'. Measured live 2026-09-05 against GET /api/requests: data roots are exactly ['items','pagination']. RESPONSE SIZE: fields controls how much each row carries -- default 'summary' returns lightweight rows (~1KB each: id, title, status{id,name,color}, priority{key,name,color}, company{...}, department{...}, assignedTo, deadline, isOverdue, sla, commentCount, fileCount). NOTE: identity fields are NESTED GROUPS in responses (status.name, priority.key, company.id) — but QUERY/FILTER keys stay FLAT (statusId, companyId, statusName in Query Builder). Use fields:'detail' when you need description/effort/counts, or fields:'full' for everything incl. customFields/stakeholders (LARGE — S-A2 kanit: 44 talep tam moduyla ~300KB).${MASKING_NOTE}${EMPTY_SCOPE_NOTE}`,
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -1161,7 +1428,8 @@ const TOOLS = [
         overdue: {
           type: 'boolean',
           description:
-            'true => geciken/overdue: deadline in the past AND not in a final status. Shorthand for deadlineDaysRemaining[operator]=lt&deadlineDaysRemaining[value]=0 combined with openOnly.',
+            'true => geciken/overdue: deadline in the past AND not in a final status. Shorthand for deadlineDaysRemaining[operator]=lt&deadlineDaysRemaining[value]=0 combined with openOnly. ' +
+            'MUTUALLY EXCLUSIVE with deadlineWithinDays (same backend parameter pair); when both are set, overdue WINS.',
         },
         slaStatus: {
           type: 'array',
@@ -1188,13 +1456,16 @@ const TOOLS = [
         deadlineWithinDays: {
           type: 'integer',
           description:
-            'Deadline within N days from now (i.e. deadlineDaysRemaining[operator]=lte,value=N).',
+            'Deadline within N days from now (i.e. deadlineDaysRemaining[operator]=lte,value=N). ' +
+            'MUTUALLY EXCLUSIVE with overdue: both map to the same backend parameter pair, so ' +
+            'if overdue is also set this one is IGNORED. Pick one — they ask opposite questions ' +
+            '(already late vs. due soon).',
         },
         fields: {
           type: 'string',
           enum: ['summary', 'detail', 'full'],
           description:
-            "Response projection profile: 'summary' (default, lightweight ~1KB/row: id/requestNumber/title/statusName/priority/assignee/deadline/isOverdue/slaStatus/commentCount/fileCount), 'detail' (adds description/effort/all counts), 'full' (everything incl. customFields/stakeHolders — LARGE).",
+            "Response projection profile: 'summary' (default, lightweight ~1KB/row: id/title/status{id,name,color}/priority{key,name,color}/company/department/assignedTo/deadline/isOverdue/sla/commentCount/fileCount), 'detail' (adds description/effort/all counts), 'full' (everything incl. customFields/stakeholders — LARGE). Identity fields are NESTED GROUPS; filter keys stay FLAT.",
         },
       },
     },
@@ -1206,7 +1477,7 @@ const TOOLS = [
   {
     name: 'list_users',
     description:
-      'List/search SysTa users (kullanicilar) with pagination and filters (search, companyId, departmentId). Wraps GET /api/users?search=... Prefer resolve_user_by_name when you have a single name and want the id -- this tool is for browsing/multiple hits. Returns {id, fullName, email, companyName, departmentName} per user (subset).',
+      'List/search SysTa users (kullanicilar) with pagination and filters (search, companyId, departmentId). Wraps GET /api/users?search=... Prefer resolve_user_by_name when you have a single name and want the id -- this tool is for browsing/multiple hits. Returns {id, fullName, email, company{id,code,name,type}, department{id,code,name}} per user — identity fields are NESTED GROUPS (company.name, NOT companyName). Filter keys stay FLAT (companyId, departmentId).',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -1240,7 +1511,7 @@ const TOOLS = [
   {
     name: 'resolve_user_by_name',
     description:
-      "Resolve a person's name (isim -> userId) for assignments and filters. Returns {userId, fullName, ambiguity} when a UNIQUE match is found; when MULTIPLE users match (e.g. 3 'Ahmet' users) returns {ambiguity:true, candidates:[{id, fullName, companyName, departmentName}], hint:'ASK the user which one'} -- DO NOT auto-pick the first candidate. Use userId with assign_request / assignedTo. When 'me/bana' is meant, use list_capabilities user.id instead (no resolve needed).",
+      "Resolve a person's name (isim -> userId) for assignments and filters. Returns {userId, fullName, company{id,name}, department{id,name}, ambiguity} (same nested shape as list_users) when a UNIQUE match is found; when MULTIPLE users match (e.g. 3 'Ahmet' users) returns {ambiguity:true, candidates:[{id, fullName, email, company{id,name}, department{id,name}}], hint:'ASK the user which one'} -- DO NOT auto-pick the first candidate. Use userId with assign_request / assignedTo. When 'me/bana' is meant, use list_capabilities user.id instead (no resolve needed).",
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -1297,8 +1568,11 @@ const TOOLS = [
               ambiguity: false,
               userId: u.id,
               fullName: u.fullName,
-              companyName: u.companyName || null,
-              departmentName: u.departmentName || null,
+              // `list_users` ile AYNI sekil: API'nin nested gruplari aynen
+              // gecirilir (Faz 33). Duz `companyName` ilan etmek ayni kavrami
+              // iki aracta iki sekilde ogretiyordu.
+              company: kullaniciGrubu(u.company),
+              department: kullaniciGrubu(u.department),
             },
           },
         };
@@ -1316,8 +1590,8 @@ const TOOLS = [
               id: u.id,
               fullName: u.fullName,
               email: u.email || null,
-              companyName: u.companyName || null,
-              departmentName: u.departmentName || null,
+              company: kullaniciGrubu(u.company),
+              department: kullaniciGrubu(u.department),
             })),
           },
         },
@@ -1362,7 +1636,11 @@ const TOOLS = [
       },
     },
     handler: async (args) => {
-      const body = { requestIds: args.requestIds, updates: args.updates };
+      // `updates` tek nesne (tum taleplere ayni degisiklik); nested gider.
+      const body = {
+        requestIds: args.requestIds,
+        updates: toNestedWriteBody('request', args.updates),
+      };
       if (args.reason) {
         body.reason = args.reason;
       }
@@ -1600,7 +1878,7 @@ const TOOLS = [
   },
   {
     name: 'create_request',
-    description: `Create a SysTa request (talep). Requires the "request.create" scope. Returns the created request under data.request. PROACTIVE (recommended): call prepare_create_request(companyId) FIRST -- it returns the active form's required fields AND valid ids (statuses/categories/organizations) so you fill them up front and avoid the 400 roundtrip. The required set is DYNAMIC and PER-COMPANY: title/companyId/statusId are the baseline (+ at least one assignment: assignedTo OR assignedTeams), but the request form that applies to THIS companyId may require more system fields (e.g. categoryId, organizationId). This vendor may run several active request forms at once; statusId/categoryId are FORM-ISOLATED and an id from another company's form is REJECTED, so resolve them via prepare_create_request(companyId) rather than reusing ids. If you skip prepare_, on a missing field the API returns 400 VALIDATION_FAILED naming it via details[].fieldKey -- add it and retry. For fields beyond this tool, use systa_api_call POST /requests. ONEMLI (talep 166 #60): verdigin \`description\` talebin ILK YORUMU (commentNo 1) olarak materyalize edilir; ZENGIN icerik istiyorsan (tablo/kod blogu/bicimli metin) \`description\` yerine systa_api_call POST /requests ile \`descriptionJson\` alanina TipTap doc gonder (tablo dahil) -- bu da comment #1 olur. Yani tabloyu talep ACARKEN descriptionJson icinde ver; AYRICA ayri bir yorum EKLEME (yoksa cift yorum olusur). Icerigi yalnizca ayri yorumda istiyorsan description bos birak.${RULE_ENGINE_NOTE}`,
+    description: `Create a SysTa request (talep). Requires the "request.create" scope. Returns the created request under data.request. PROACTIVE (recommended): call prepare_create_request(companyId) FIRST -- it returns the active form's required fields AND valid ids (statuses/categories/organizations) so you fill them up front and avoid the 400 roundtrip. The required set is DYNAMIC and PER-COMPANY: title/companyId/statusId are the baseline (+ at least one assignment: assignedTo OR assignedTeams), but the request form that applies to THIS companyId may require more system fields (e.g. categoryId, organizationId). This vendor may run several active request forms at once; statusId/categoryId are FORM-ISOLATED and an id from another company's form is REJECTED, so resolve them via prepare_create_request(companyId) rather than reusing ids. If you skip prepare_, on a missing field the API returns 400 VALIDATION_FAILED naming it via details[].fieldKey -- add it and retry. For fields beyond this tool, use systa_api_call POST /requests with a NESTED body ({ status:{id}, company:{id}, category:{id}, priority:{key} }) -- this tool converts its flat args for you; the raw endpoint does not. ONEMLI (talep 166 #60): verdigin \`description\` talebin ILK YORUMU (commentNo 1) olarak materyalize edilir; ZENGIN icerik istiyorsan (tablo/kod blogu/bicimli metin) \`description\` yerine systa_api_call POST /requests ile \`descriptionJson\` alanina TipTap doc gonder (tablo dahil) -- bu da comment #1 olur. Yani tabloyu talep ACARKEN descriptionJson icinde ver; AYRICA ayri bir yorum EKLEME (yoksa cift yorum olusur). Icerigi yalnizca ayri yorumda istiyorsan description bos birak.${RULE_ENGINE_NOTE}`,
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -1634,6 +1912,11 @@ const TOOLS = [
           description:
             'Organization-unit id (optional; may be required by the active form; must belong to companyId)',
         },
+        subOrganizationId: {
+          type: 'integer',
+          description:
+            'Sub-organization-unit id (optional; must be a DIRECT child of organizationId -- the org tree is single-level).',
+        },
         departmentId: { type: 'integer', description: 'Department id (optional)' },
         projectId: { type: 'integer', description: 'Link to a project (optional)' },
         priority: {
@@ -1693,7 +1976,7 @@ const TOOLS = [
           body[key] = args[key];
         }
       }
-      return systaFetch('POST', '/requests', { body });
+      return systaFetch('POST', '/requests', { body: toNestedWriteBody('request', body) });
     },
   },
   {
@@ -1712,6 +1995,12 @@ const TOOLS = [
     },
     handler: async (args) => {
       const companyId = args.companyId;
+      // Lookup satirlari KENDI adlarini tasir (`statusName` bir durum listesinde
+      // durumun kendi adidir — oz-referans, DUZ kalir). Canli olculdu
+      // (2026-09-01): /statuses `statusName`, /categories `categoryName`,
+      // /organizations `unitName`, /departments `departmentName`. Nested
+      // `x.status?.name` dallari OLU KODDU — bu liste atif degil varlik listesi;
+      // shim karar 1.2 geregi kaldirildi (BF-57).
       const nameOf = (x) =>
         x.name ??
         x.statusName ??
@@ -1900,6 +2189,364 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       });
     },
   },
+  {
+    name: 'start_work_session',
+    description: `Claim a record before you touch it: opens YOUR work session on one request or one task card.
+
+WHY THIS EXISTS. SysTa shows a live "working on it" indicator to every human and every agent looking at that record. Without a session your edits are invisible to the people around you, and two agents silently rewrite each other's work. Starting a session is the cheapest collision prevention SysTa has.
+
+THE COORDINATION LOOP, in order:
+  1. list_active_work_sessions  -> is somebody already on this record?
+  2. if yes -> send_work_session_message and agree who takes what
+  3. start_work_session         -> claim it, with a note saying WHERE you are
+  4. work; call send_work_session_heartbeat while you work (see below)
+  5. end_work_session           -> release the claim when you stop
+
+TARGET. Give EXACTLY ONE of requestId or cardId. Both or neither is refused with EXACTLY_ONE_TARGET. cardId is the card's GLOBAL id (card.id from get_request_board), not the per-board "#3" sequence.
+
+THE NOTE IS THE POINT. description is free text (max 2000 chars) and it is what other agents actually read before deciding to wait or proceed. Write the file or the area, not the intention: "src/models/request/requestCrudModel.js, create path" beats "working on request stuff".
+
+LIFETIME. A session stays live until you end it or it goes silent for 15 minutes. Silence closes it automatically, and the auto-close records the LAST SIGNAL time as the end, not the moment of closing — so an abandoned session does not inflate anybody's effort.
+
+Requires "work-session.manage". Reading other people's sessions is a separate, weaker privilege ("work-session.view-active").`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        requestId: {
+          type: 'integer',
+          description: 'Request number. Give this OR cardId, never both.',
+        },
+        cardId: {
+          type: 'integer',
+          description: 'Card GLOBAL id from get_request_board. Give this OR requestId, never both.',
+        },
+        description: {
+          type: 'string',
+          description:
+            'What you are doing, ideally the file or area. Max 2000 characters. Other agents read this before deciding to wait.',
+        },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      if (args.requestId !== undefined) {
+        body.requestId = args.requestId;
+      }
+      if (args.cardId !== undefined) {
+        body.cardId = args.cardId;
+      }
+      if (args.description !== undefined) {
+        body.description = args.description;
+      }
+      return systaFetch('POST', '/work-sessions', { body });
+    },
+  },
+  {
+    name: 'send_work_session_heartbeat',
+    description: `Tell SysTa you are still working. Refreshes your session's last-signal time.
+
+WHEN TO CALL. A session with no signal for 15 minutes is closed automatically and your claim disappears while you are still editing. MCP calls are not a heartbeat by themselves, so on any stretch of work longer than about ten minutes — a long build, a test run, a big refactor — call this between steps. A cheap call now beats losing the claim and colliding later.
+
+WHAT IT DOES NOT DO. It does not extend effort, change status or touch the record. It only says "still here".
+
+sessionId comes from start_work_session or list_my_work_sessions. Ending an already-ended session is not retryable: if you get WORK_SESSION_ENDED (409) the claim is gone — start a new session instead of retrying the heartbeat.
+
+Requires "work-session.manage".`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['sessionId'],
+      properties: {
+        sessionId: { type: 'integer', description: 'Your open session id.' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('POST', `/work-sessions/${encodeURIComponent(args.sessionId)}/heartbeat`),
+  },
+  {
+    name: 'end_work_session',
+    description: `Release your claim: closes YOUR work session on a record.
+
+CALL THIS WHEN YOU STOP, not when the task is finished — pausing for an hour is also stopping. A live session means "I am in this file right now"; leaving it open while you are elsewhere makes the indicator lie and makes the next agent wait for nothing.
+
+endedAt is optional and almost never needed: omit it and the server stamps the moment of the call. Pass it only to record a stop that already happened, as an ISO-8601 timestamp with offset.
+
+Ending a session does NOT delete its conversation — read_messages(sessionId) still returns what was said. But a closed session accepts no new messages: send_work_session_message returns WORK_SESSION_ENDED (409).
+
+Requires "work-session.manage".`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['sessionId'],
+      properties: {
+        sessionId: { type: 'integer', description: 'Your open session id.' },
+        endedAt: {
+          type: 'string',
+          description: 'Optional ISO-8601 timestamp with offset. Omit to stamp now.',
+        },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      if (args.endedAt !== undefined) {
+        body.endedAt = args.endedAt;
+      }
+      return systaFetch('POST', `/work-sessions/${encodeURIComponent(args.sessionId)}/end`, {
+        body,
+      });
+    },
+  },
+  {
+    name: 'update_work_session_note',
+    description: `Rewrite the note on your own open session — the text other agents read before deciding whether to wait for you.
+
+WHEN TO USE. You moved. You claimed the model layer, you are now in the controller; the stale note sends the next agent into the file you just entered. Updating the note is how a long session stays honest.
+
+Pass description: null to clear the note entirely (the session stays open). An empty string is not the way to clear it.
+
+Requires "work-session.manage".`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['sessionId', 'description'],
+      properties: {
+        sessionId: { type: 'integer', description: 'Your open session id.' },
+        description: {
+          type: ['string', 'null'],
+          description: 'New note, max 2000 characters. null clears it.',
+        },
+      },
+    },
+    handler: (args) =>
+      systaFetch('PATCH', `/work-sessions/${encodeURIComponent(args.sessionId)}`, {
+        body: { description: args.description },
+      }),
+  },
+  {
+    name: 'list_my_work_sessions',
+    description: `Your OWN open sessions. Use it to find a sessionId you forgot, or to check you are not holding a claim you already walked away from.
+
+Typical uses: you started a session, did a long piece of work, and need the id for send_work_session_heartbeat or end_work_session; or you are starting fresh and want to close whatever you left open earlier.
+
+This is the "mine" view. For everybody else's live claims use list_active_work_sessions.
+
+Requires "work-session.manage".`,
+    inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+    handler: () => systaFetch('GET', '/work-sessions/active'),
+  },
+  {
+    name: 'list_work_session_history',
+    description: `Past sessions on one record, newest first — who worked on this before, when, and what note they left.
+
+Give EXACTLY ONE of requestId or cardId, same rule as start_work_session.
+
+WHEN TO USE. Before picking up an unfamiliar record: the last note often says where the previous person stopped. Also for effort questions ("how much sitting did this card take") — each row carries its start and end.
+
+PAGING. Results run newest to oldest, so the cursor moves BACKWARD: pass beforeId = the id of the oldest row you have, and you get the ones before it. limit defaults to 20, max 100.
+
+Requires "work-session.view-active".`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        requestId: { type: 'integer', description: 'Request number. Give this OR cardId.' },
+        cardId: { type: 'integer', description: 'Card GLOBAL id. Give this OR requestId.' },
+        limit: { type: 'integer', description: 'Page size, default 20, max 100.' },
+        beforeId: {
+          type: 'integer',
+          description: 'Oldest session id you already have; returns the ones before it.',
+        },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', '/work-sessions/history', {
+        query: {
+          requestId: args.requestId,
+          cardId: args.cardId,
+          limit: args.limit,
+          beforeId: args.beforeId,
+        },
+      }),
+  },
+  {
+    name: 'list_active_work_sessions',
+    description: `Who is working on what RIGHT NOW — everybody's live claims, not just yours. Call this BEFORE you start editing a request or a task card. It is step one of the coordination loop:
+
+  1. list_active_work_sessions      -> is somebody already on this record?
+  2. if yes -> send_work_session_message and agree who takes what
+  3. start_work_session             -> claim it, with a note saying WHERE you are
+  4. send_work_session_heartbeat    -> while you work, on anything longer than ~10 minutes
+  5. end_work_session               -> release the claim when you stop
+
+Each item identifies the person, the target (request or card), when they started, their last signal, and the free-text note they left ("I am in src/models/foo.js"). That note is the most useful field for avoiding collisions; read it before deciding.
+
+A session stays listed until it is stopped or goes silent for 15 minutes, so a listed session is a live claim, not history. For finished sessions on one record use list_work_session_history; for your own open claims use list_my_work_sessions.
+
+FINDING SOMEBODY IS NOT A STOP SIGN. It means talk first. Two agents on the same request but different files is normal and fine — what is not fine is starting silently.
+
+Requires "work-session.view-active". You only see sessions inside your access scope; sessions on records you cannot see are filtered out rather than refused.`,
+    inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+    handler: () => systaFetch('GET', '/work-sessions/active/all'),
+  },
+  {
+    name: 'send_work_session_message',
+    description: `Write to somebody's OPEN work session — the way two agents avoid stepping on each other.
+
+WHEN TO USE. You called list_active_work_sessions (or get_request_board) and found someone already working on the record you were about to touch. Do not silently start beside them: say what you need. Typical lines that actually prevent conflicts:
+  * "I am editing src/models/foo.js — leaving the controller to you"
+  * "Holding db/migrations/1042 until you land yours"
+  * "My API contract is {POST /api/x -> {id}} — you can build against it"
+
+Only OPEN sessions accept messages. A session that has ended returns WORK_SESSION_ENDED (409); that is not a retryable error — the person stopped working, so read the record instead, leave a lasting note with send_room_message, or claim it yourself with start_work_session.
+
+WAITING FOR THE ANSWER. A session message does not notify you back. If you cannot continue without the reply, wait inside listen_room on that record's room; if you can keep working, come back later with read_messages(sessionId, afterId).
+
+Reading needs "work-session.view-active"; WRITING needs "collaboration.message". Seeing coordination and joining it are separate privileges.
+
+Body is plain text, at most 2000 characters. Trailing and leading spaces are trimmed; an empty body is refused.`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['sessionId', 'body'],
+      properties: {
+        sessionId: {
+          type: 'integer',
+          description: 'Open work session id — read it from list_active_work_sessions.',
+        },
+        body: { type: 'string', description: 'Plain text, 1..2000 characters.' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('POST', `/work-sessions/${encodeURIComponent(args.sessionId)}/messages`, {
+        body: { body: args.body },
+      }),
+  },
+  {
+    name: 'send_room_message',
+    description: `Write to a ROOM: a project, a request or a task card. Unlike a session message this outlives any single work session — use it when the note should stay for whoever comes next, or when nobody is working right now.
+
+THERE IS NO "JOIN". A room is not a channel you subscribe to; it is the record itself. If your access scope already lets you see that project, request or card, you can read and write its room immediately. Nothing to create, nothing to join, no membership call. Out-of-scope rooms are refused outright rather than returned empty, so a refusal means "not yours", not "not there".
+
+WHICH ROOM MATCHES WHICH SCREEN. A human reading your message sees it on the record's own surface, so pick the room by where the conversation belongs:
+  * roomType "request" + the request NUMBER  -> the request's chat, visible on the request detail screen
+  * roomType "card" + the card's GLOBAL id   -> the task card's chat (card.id from get_request_board, NOT the per-board "#3" sequence)
+  * roomType "project" + the project id      -> the project-level chat, which is what the Gantt view and the k&k chart open when somebody clicks the project node
+
+On the Gantt and the k&k chart a node can be a project, a request or a card. Send to the room of the thing the node represents: a message about one request does not belong in the project room just because the reader is looking at a chart.
+
+ROOM OR SESSION. The message is about the record -> room. The message is about somebody's current sitting -> session. "The migration numbering restarts at 1042" belongs to the room; "I am in that file right now" belongs to the session.
+
+Requires "collaboration.message". Reading is a weaker privilege than writing: a role may watch coordination without joining it.
+
+Body is plain text, at most 2000 characters.`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['roomType', 'roomId', 'body'],
+      properties: {
+        roomType: { type: 'string', enum: ['project', 'request', 'card'] },
+        roomId: { type: 'integer', description: 'Project id, request number, or card GLOBAL id.' },
+        body: { type: 'string', description: 'Plain text, 1..2000 characters.' },
+      },
+    },
+    handler: (args) =>
+      systaFetch(
+        'POST',
+        `/rooms/${encodeURIComponent(args.roomType)}/${encodeURIComponent(args.roomId)}/messages`,
+        { body: { body: args.body } },
+      ),
+  },
+  {
+    name: 'read_messages',
+    description: `Read a conversation, or ask "what arrived since I last looked".
+
+Give EITHER sessionId (one work session's conversation) OR roomType+roomId (a room's conversation). Giving both is refused rather than guessed. A session conversation ends with that session: starting work again tomorrow opens a NEW conversation, so yesterday's lines do not reappear. A room conversation is permanent and survives every session.
+
+CURSOR. Pass afterId = the id of the last message you already read; you get only what came after. Do not use timestamps as a cursor — the API renders milliseconds while the column stores microseconds, so a timestamp cursor returns the same row twice (measured 2026-09-08). The response carries pagination.nextAfterId for the next call and pagination.hasMore.
+
+HOW TO GET NEW MESSAGES — pick one, do not do both:
+  * You are WAITING right now (you asked a question, you need the answer before you continue) -> listen_room. It blocks for a bounded time and returns what arrived. No polling loop, no wasted calls.
+  * You are WORKING and will check back later (you just want to know what happened while you were busy) -> read_messages with afterId. One call per check-in, not a loop. Between check-ins do your actual work.
+
+There is no push channel to an MCP client and no background subscription: nothing wakes you up on its own. Either you wait inside listen_room, or you come back and ask with afterId. A tight poll loop is the wrong answer to both.
+
+FIRST CALL: read once with no cursor to get the recent history, remember pagination.nextAfterId, and use that from then on.`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        sessionId: { type: 'integer', description: 'Work session id (session conversation).' },
+        roomType: { type: 'string', enum: ['project', 'request', 'card'] },
+        roomId: { type: 'integer', description: 'Project id, request number, or card GLOBAL id.' },
+        afterId: {
+          type: 'integer',
+          description: 'Last message id you already read. Omit for the first page.',
+        },
+        limit: { type: 'integer', description: 'Page size, default 50, max 200.' },
+      },
+    },
+    handler: (args) => {
+      const query = { afterId: args.afterId, limit: args.limit };
+      if (args.sessionId) {
+        // Iki hedef birden verilirse hangisinin kastedildigi belirsizdir;
+        // sessizce birini secmek yanlis konusmayi okutur.
+        if (args.roomType || args.roomId) {
+          throw new Error('Give either sessionId or roomType+roomId, not both');
+        }
+        return systaFetch('GET', `/work-sessions/${encodeURIComponent(args.sessionId)}/messages`, {
+          query,
+        });
+      }
+      if (!args.roomType || !args.roomId) {
+        throw new Error('Give either sessionId, or both roomType and roomId');
+      }
+      return systaFetch(
+        'GET',
+        `/rooms/${encodeURIComponent(args.roomType)}/${encodeURIComponent(args.roomId)}/messages`,
+        { query },
+      );
+    },
+  },
+  {
+    name: 'listen_room',
+    description: `Wait for live activity in a room instead of polling. Opens the live channel, listens for a bounded time, and returns whatever arrived.
+
+THIS IS A BOUNDED WAIT, NOT A SUBSCRIPTION. It returns after "seconds" (default 30, max 120), or earlier once maxEvents is reached. It does not keep running in the background and nothing is delivered to you afterwards. stoppedBy tells you why it returned: timeout | maxEvents | streamEnded. To keep waiting, call it again.
+
+WHEN TO USE IT. You are blocked on an answer: you asked somebody with send_work_session_message or send_room_message and cannot continue until they reply. Or you are waiting for a colleague to release a file. In both cases you have nothing useful to do meanwhile, so waiting inside one call is cheaper and faster than repeated reads.
+
+WHEN NOT TO USE IT. You have work to do. Then do the work and check in afterwards with read_messages(afterId). Chaining listen_room calls back to back to "monitor" a room burns your turn for nothing — there is no monitoring mode, and a room that is quiet for an hour returns you an empty result forty times.
+
+NOTHING IS LOST EITHER WAY. Events carry the same message shape as read_messages, so there is nothing new to parse. If the stream drops mid-wait, resume with read_messages(afterId = last id you saw) and continue from exactly there. Heartbeats are transport-level keepalives and never appear as events, so an empty result genuinely means "nobody said anything".
+
+Requires "work-session.view-active". You only reach rooms your access scope already allows.`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['roomType', 'roomId'],
+      properties: {
+        roomType: { type: 'string', enum: ['project', 'request', 'card'] },
+        roomId: { type: 'integer', description: 'Project id, request number, or card GLOBAL id.' },
+        seconds: {
+          type: 'integer',
+          description: 'How long to wait before returning, default 30, max 120.',
+        },
+        maxEvents: {
+          type: 'integer',
+          description: 'Return early once this many events arrived, default 50.',
+        },
+      },
+    },
+    handler: (args) =>
+      systaStream(
+        `/rooms/${encodeURIComponent(args.roomType)}/${encodeURIComponent(args.roomId)}/stream`,
+        {
+          seconds: Math.min(Number(args.seconds) || 30, 120),
+          maxEvents: Math.min(Number(args.maxEvents) || 50, 200),
+        },
+      ),
+  },
   {
     name: 'list_allowed_transitions',
     description:
@@ -1954,11 +2601,15 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
           `/requests/${encodeURIComponent(args.requestNumber)}/allowed-transitions`,
         );
         const allowed = allowedRes?.data?.data?.allowedTransitions || [];
+        // Gecis satiri `toStatusKey` tasir (canli: `{fromStatusId, toStatusId,
+        // toStatusName, toStatusKey, toStatusColor}`); `statusKey` HIC yoktu, bu
+        // dal hicbir zaman eslesmiyor ve yavas cozumleme yoluna dusuyordu (BF-56).
         const hit = allowed.find(
-          (t) => String(t.statusKey || '').toLowerCase() === String(args.statusKey).toLowerCase(),
+          (t) => String(t.toStatusKey || '').toLowerCase() === String(args.statusKey).toLowerCase(),
         );
         if (hit) {
-          statusId = hit.id ?? hit.statusId;
+          // Gecis satirinin hedefi `toStatusId`dir; `id`/`statusId` yoktu (BF-56).
+          statusId = hit.toStatusId ?? hit.id ?? hit.statusId;
         }
         if (statusId == null) {
           // Yedek: TALEBIN KENDI formuna scope'lu statu listesi (global liste
@@ -1977,7 +2628,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
         );
       }
       const res = await systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, {
-        body: { statusId },
+        body: toNestedWriteBody('request', { statusId }),
       });
       if (args.comment && String(args.comment).trim()) {
         const doc = {
@@ -2044,7 +2695,9 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
           body[k] = v;
         }
       }
-      return systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, { body });
+      return systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, {
+        body: toNestedWriteBody('request', body),
+      });
     },
   },
   {
@@ -2072,7 +2725,9 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       if (Array.isArray(args.assignedTeams)) {
         body.assignedTeams = args.assignedTeams;
       }
-      return systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, { body });
+      return systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, {
+        body: toNestedWriteBody('request', body),
+      });
     },
   },
   {
@@ -2315,7 +2970,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       if (args.requestNote) {
         body.requestNote = args.requestNote;
       }
-      return systaFetch('POST', '/approvals/batch', { body });
+      return systaFetch('POST', '/approvals/batch', { body: toNestedWriteBody('approval', body) });
     },
   },
   {
@@ -2395,7 +3050,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
           body[k] = v;
         }
       }
-      return systaFetch('POST', '/projects', { body });
+      return systaFetch('POST', '/projects', { body: toNestedWriteBody('project', body) });
     },
   },
   {
@@ -2464,7 +3119,9 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
           body[k] = v;
         }
       }
-      return systaFetch('PUT', `/projects/${encodeURIComponent(args.id)}`, { body });
+      return systaFetch('PUT', `/projects/${encodeURIComponent(args.id)}`, {
+        body: toNestedWriteBody('project', body),
+      });
     },
   },
   {
@@ -3006,7 +3663,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
           body[k] = v;
         }
       }
-      return systaFetch('POST', '/releases/lists', { body });
+      return systaFetch('POST', '/releases/lists', { body: toNestedWriteBody('release', body) });
     },
   },
   {
@@ -3047,7 +3704,9 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
     },
     handler: (args) => {
       if (Array.isArray(args.items) && args.items.length) {
-        return systaFetch('POST', '/releases/items', { body: args.items });
+        return systaFetch('POST', '/releases/items', {
+          body: args.items.map((oge) => toNestedWriteBody('release', oge)),
+        });
       }
       const body = {};
       for (const [k, v] of Object.entries(args)) {
@@ -3055,7 +3714,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
           body[k] = v;
         }
       }
-      return systaFetch('POST', '/releases/items', { body });
+      return systaFetch('POST', '/releases/items', { body: toNestedWriteBody('release', body) });
     },
   },
   {
@@ -3307,7 +3966,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
   {
     name: 'systa_api_call',
     description:
-      'Generic SysTa REST API call. Use for any endpoint not covered by a specific tool (create/update/comment, etc.). The API key scope is enforced server-side: out-of-scope calls return 403. path is relative to the API base (e.g. "/requests/42/comments"). You may paste a path verbatim from list_capabilities/describe_endpoint even though those include the "/api" prefix — a leading "/api" is auto-stripped (the base URL already ends in /api), so "/api/requests" and "/requests" both work.',
+      'Generic SysTa REST API call. Use for any endpoint not covered by a specific tool (create/update/comment, etc.). The API key scope is enforced server-side: out-of-scope calls return 403. path is relative to the API base (e.g. "/requests/42/comments"). WRITE BODIES ARE NESTED (POST/PUT/PATCH on entities): send identity references as groups exactly as describe_endpoint(fields) shows them -- { status: { id: 9 }, company: { id: 12 }, priority: { key: "high" }, project: null } -- NOT flat statusId/companyId; flat keys are a deprecated transitional form and will be rejected. Query/filter keys on GET stay FLAT (statusId, companyId). Named tools (create_request, update_request, change_request_status, create_project...) do this conversion for you. You may paste a path verbatim from list_capabilities/describe_endpoint even though those include the "/api" prefix — a leading "/api" is auto-stripped (the base URL already ends in /api), so "/api/requests" and "/requests" both work.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -3460,7 +4119,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       'shown), each with its HTTP methods, safety class (read_only/idempotent/mutating/' +
       'destructive) and required permission. Also returns SysTa overview, TR glossary and your ' +
       'user (who-am-i). Call this FIRST. For a broad key the full catalog can be large: pass ' +
-      'summary=true to get only orientation + module names with endpoint counts (a few KB), then ' +
+      'summary=true to get only orientation + module names with endpoint counts (~57KB vs ~483KB compact), then ' +
       `pass module="<name>" to drill into one module. No args = full compact catalog.${MODULE_GATE_NOTE}`,
     inputSchema: {
       type: 'object',
@@ -3659,7 +4318,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
           body[k] = args[k];
         }
       }
-      return systaFetch('POST', '/effort/entries', { body });
+      return systaFetch('POST', '/effort/entries', { body: toNestedWriteBody('effort', body) });
     },
   },
   {
@@ -4013,7 +4672,9 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
           },
         });
       }
-      return systaFetch('PATCH', `/effort/entries/${encodeURIComponent(args.entryId)}`, { body });
+      return systaFetch('PATCH', `/effort/entries/${encodeURIComponent(args.entryId)}`, {
+        body: toNestedWriteBody('effort', body),
+      });
     },
   },
   {
@@ -4774,4 +5435,8 @@ module.exports = {
   sanitizeFileName,
   mimeForFileName,
   resolveSavePath,
+  // Nested yazma govdesi (Faz 21 / BF-92) — spec-sync testi icin export edilir
+  toNestedWriteBody,
+  YAZMA_YOLLARI,
+  YAZMA_GRUPLARI,
 };