systa-mcp 1.0.8 → 1.1.0

package/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 1.0.8
+version: 1.1.0
 name: systa
 description: |
   Drive SysTa (Talep Takip Sistemi / SysTa) — a
@@ -94,36 +94,45 @@ 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                  |
-| gorev, task, kart, card                                   | kanban          | manage_request_card / move_request_card         |
-| pano, board, kanban / kolon, column, asama, liste         | kanban          | get_request_board                               |
-| efor, durum, oncelik, atanan, planla, denetim, gecmis     | request         | get_request / list_requests                     |
-| 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    |
-| sla, sure taahhudu                                        | sla             | (sla endpoints)                                 |
-| release, surum, go/no-go, deployment                      | release         | create_release_list / add_release_item          |
-| 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, anket, memnuniyet, geri bildirim | ratings         | POST /api/ratings                               |
-| github, repo, pull request, commit, entegrasyon           | github          | GET /api/github/connection                      |
-| gosterge paneli, dashboard, widget, ozet, grafik, panel   | dashboard       | GET /api/dashboard/init                         |
+| 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 |
+| 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                                                  |
+| efor, durum, oncelik, atanan, planla, denetim, gecmis        | request         | get_request / list_requests                                       |
+| 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                      |
+| sla, sure taahhudu                                           | sla             | (sla endpoints)                                                   |
+| release, surum, go/no-go, deployment                         | release         | create_release_list / add_release_item                            |
+| 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, anket, memnuniyet, geri bildirim    | ratings         | POST /api/ratings                                                 |
+| 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
 > bir kelime için `list_capabilities` çağır — anahtarının erişebildiği güncel modül/alias
@@ -154,20 +163,26 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 ### 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.
-2. Defaults: `channel='API'` (AI/MCP source), `companyId` ← who-am-i, `statusId` ← default open/new status (resolve via `GET /api/statuses`, pick the non-final entry status), `priority='normal'` unless the user signals "acil/critical". `description` can be a plain string.
-3. Submit; report "Talep #<num> açıldı — '<title>'". If the user also said "bana ata", chain assignment below.
+2. Defaults: `channel='API'` (AI/MCP source), `statusId` ← default open/new status (resolve via `GET /api/statuses`, pick the non-final entry status), `priority='normal'` unless the user signals "acil/critical". `description` can be a plain string. **`companyId` — DIKKAT:** genelde `user.companyId` DEĞİL — B2B talepler MÜŞTERİ şirketi için açılır. Şirket adı netlesmediyse `systa_api_call GET /companies?search=<ad>` ile çöz veya kullanıcıya SOR. `prepare_create_request(companyId)` proaktif seçenekleri döner.
+3. **Efor** (`estimatedEffort`/`personDay`): KANONIK GÜN. Kullanıcı "N saat" derse ÖNCE `list_capabilities.effortPolicy.hoursPerDay` ile böl (varsayılan 8), sonra yaz. "8 saat" → `estimatedEffort=1` (8/8=1 gün), "4 saat" → `estimatedEffort=0.5`. Aynı kural `manage_request_card.estimatedEffort` ve `bulk_update_requests.updates.estimatedEffort` için de geçerli.
+4. Submit; report "Talep #<num> açıldı — '<title>'". If the user also said "bana ata", chain assignment below.
 
 ### Üzerimdeki işler / talepleri listele (what's on my plate) — `list_requests` → `GET /api/requests`
 
-- "taleplerim / on me" → `assignedTo=<my userId>`. "açık/open" → final olmayan durumlar. Default `limit=20-50`, sort `created_at desc`, `companyId` from scope. 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). 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.
 
 ### Talep detayı (show a request) — `get_request` → `GET /api/requests/:requestNumber`
 
 - Resolve the user's number/title to `requestNumber`. If ambiguous, `list_requests` first to find candidates, then fetch.
+- **Alt kaynaklar (dedicated tools):** yorumlar → `list_request_comments(requestNumber)` (her yorumun `fileIds[]`'ı vardır — yorum ekleri buradan bulunur); ekler → `list_request_files(requestNumber)` (yalnız talep-birinci-seviye ekler; yorum/kart ekleri için `download_request_file` description'ındaki 7 kaynaklık listeye bak); değişiklik geçmişi → `list_request_history(requestNumber)` (kim ne değiştirdi, actor/timestamp/field/oldValue/newValue).
 
 ### Bana / birine ata (assign) — `assign_request` → `PUT /api/requests/:requestNumber`
 
-- "bana/üzerime" → `assignedTo=<my userId>`. A name → resolve via user lookup (`GET /api/users?search=`) to `userId`. Partial update — only send `assignedTo`.
+- "bana/üzerime" → `assignedTo=<my userId>` (list_capabilities.user.id). A name → **`resolve_user_by_name(name)`** — döner {matched, ambiguity, userId | candidates[]}. Ambiguity=true (birden çok eşleşme) durumunda kullanıcıya SOR, rastgele seçme. `list_users(search, companyId, ...)` browsing/multi-hit için; tek-isim çözümü için resolve_user_by_name tercih edilir. Partial update — only send `assignedTo`.
+
+### Toplu güncelleme (bulk update) — `bulk_update_requests` → `PUT /api/requests/bulk`
+
+- Birden fazla talebe AYNI değişikliği uygula ("bunları kritik yap", "5 talebi tamamla") — `requestIds:[...] + updates:{...}` şeklinde tek çağrı. `update_request`'i loop içinde çağırma. `updates` kabul eder: statusId, assignedTo, priority, deadline, categoryId, departmentId, projectId, estimatedEffort (**GÜN**), personDay (**GÜN**), plannedStartDate, plannedEndDate. Farklı update grupları için ayrı bulk çağrıları yap. Undo isteği: `systa_api_call POST /api/requests/bulk/undo` yanıtta dönen `batchId` ile.
 
 ### Yorum ekle (comment) — `add_request_comment` → `POST /api/requests/:requestNumber/comments`
 
@@ -175,7 +190,7 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 
 ### Durum değiştir / tamamla / kapat (change status) — `change_request_status` → `PUT /api/requests/:requestNumber`
 
-- "tamamla/kapat" → pick the appropriate `is_final` status (resolve via `GET /api/statuses`). A named status → resolve to `statusId`. If the user wrote a closing note, add it as a comment; if not, don't.
+- **ÖNCE** `list_allowed_transitions(requestNumber)` çağır — transition kuralları hedef statüleri sınırlar (kategori/şirket/departman/öncelik bazlı). Dönen listede kullanıcının doğal-dil hedefini (`test asamasi`, `tamamla`, `yeniden ac`) `statusKey` / `statusId` ile eşleştir. `change_request_status` `statusId` VEYA `statusKey` alır (statusKey verirsen tool içeride list_allowed_transitions ile çözer, aksi halde global `/statuses` fallback). "tamamla/kapat" → `is_final=true` bir statü. Kullanıcı kapanış notu yazdıysa `comment` argümanı olarak geç.
 
 ### Proje aç (start a project) — `create_project` → `POST /api/projects`
 
@@ -183,16 +198,22 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 
 ### Projemi / projeleri gör + durum (list / health) — `list_projects` / `get_project_health`
 
-- List: `GET /api/projects` (default `page=1, limit=20`, recent first). "durum/sağlık" → combine `health-score` + `risk-score` + `sla-status` into one summary.
+- List: `list_projects` (default `limit=20`, recent first). Filtreler: `search`, `companyId`, `parentProjectId` (subtree — immediate children), `status`. "durum/sağlık" → combine `health-score` + `risk-score` + `sla-status` into one summary.
+- **Klonla / cogalt:** `duplicate_project(id, newProjectName?)` — kaynak projenin tanımını (isim/company/dep/org/dates/weight/planned effort/governance) yeni bir projeye kopyalar. KOPYALANMAZ: alt proje, talep, board, milestone, snapshot, gerçekleşen efor/ilerleme (bunlar yeni projede sıfırdan başlar).
 
 ### Kanban kart ekle (add a task card) — `manage_request_card` (create)
 
-- `boardId` is always tied to a `requestId` — first resolve the board (`get_request_board`, or `GET /api/requests/:requestId/kanban/hierarchy`). Defaults: first/entry column if `columnId` omitted, `priority='normal'`, unassigned unless "bana ata", `cardTitle` min 3 chars (ask to clarify if shorter). `manage_request_card` handles create / update / complete (the action is in the body) — call `describe_endpoint` if unsure of the fields.
+- `boardId` is always tied to a `requestId` — first resolve the board (`get_request_board`, or `GET /api/requests/:requestId/kanban/hierarchy`). **Board yoksa** (`get_request_board` veya `manage_request_card` yanıtı 404 `KANBAN_BOARD_NOT_FOUND` / kod 2031) — ÖNCE `create_request_board(requestId)` çağır (opsiyonel `templateId` ile şablon; şablonları `systa_api_call GET /task-boards/templates` listeler), sonra kartı ekle. Defaults: first/entry column if `columnId` omitted, `priority='normal'`, unassigned unless "bana ata", `cardTitle` min 3 chars (ask to clarify if shorter). `manage_request_card` handles create / update / complete (the action is in the body) — call `describe_endpoint` if unsure of the fields.
 
 ### Kartı taşı / tamamla (move / complete card) — `move_request_card` / `manage_request_card`
 
 - Move: `move_request_card` — resolve the target column name → `columnId` from the board detail; append to end if no position given. Complete: `manage_request_card` with the complete action — server sets `isCompleted=true`, 100%.
 
+### Sprint / plan modu + snapshot (plan lifecycle) — `create_plan_mode` → `create_plan_baseline` → `compare_plan_baseline`
+
+- **Sırayla:** (1) `create_plan_mode(name, boards?)` — sprint kapsamını aç. `boards` verirsen filterCriteria ile talepleri filtreleyen boardlar oluşur; **omit edersen tool otomatik tek varsayılan board ekler** (boş baseline'a düşmezsin). (2) `create_plan_baseline(modeId, baselineName)` — mode'un canlı durumunu snapshot alır ve `baselineId` döner. (3) `submit_plan_for_approval(baselineId, approverUserIds)` — onaya sunar. "sprinti kapat" ise `systa_api_call PATCH /api/plan/baselines/:baselineId/lifecycle` `{lifecycleStatus:'completed'}`. "plan optimize et / dagit" ise `distribute_plan_schedule`.
+- **Snapshot farkı / baseline karşılaştırması:** "son snapshot ile bugünkü durum arasında ne değişmiş" → `compare_plan_baseline(baselineId)`. Ham snapshot'ı çekmeye çalışırsan `get_plan_baseline(baselineId)` **varsayılan olarak `fields:'summary'`** kullanır ve `snapshotData`'yı DAHİL ETMEZ — metadata + counts (totalCards, totalEffort, approvalStatus, hasSnapshot) döner. Gerçekten ham snapshot lazımsa `fields:'full'` (nadir, ~800KB).
+
 ### Onaya sun / onayla / bekleyenler (approvals)
 
 - Submit (request approval): `request_approval` → `POST /api/approvals/batch`, `strategy='any_one'` default, approver names → ids. Plan onayı ayrı: `submit_plan_for_approval` → `POST /api/plan/approvals/submit` (`strategy='all_required'`).
@@ -211,6 +232,16 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 
 - `releaseType='standard'`, `requireAllStakeholderApprovals=false`, `companyId` from scope. Add items with `add_release_item`. Deployment workflow steps (`close-servers` → `start-db-migration` → `start-server-update` → `open-servers` → `complete`) are live ops — **never auto-advance blindly**; show which step you're on and confirm. Release notes: generate → review → publish (never auto-publish).
 
+### GitHub: bağla / issue aktar / push (kişisel entegrasyon) — `github.self`
+
+Kullanıcının kendi GitHub bağlantısı üzerinden talep açma/aktarma. Tümü `systa_api_call` (named tool yok); gereken scope `github.self` (anahtarda yoksa bu uçlar katalogda görünmez → kullanıcıya `github.self` scope'lu yeni anahtar üretmesini söyle).
+
+- **PAT bağlama AI'dan YAPILMAZ.** Kullanıcı GitHub fine-grained PAT'ını SysTa web arayüzünden (Ayarlar → GitHub) bağlar; AI asla PAT/secret istemez/almaz. Bağlantı yoksa kullanıcıyı oraya yönlendir.
+- **Bağlantı durumu:** `systa_api_call` `GET /github/me/connection` (maskeli meta). Bağlı değilse import/push deneme — önce web'den bağlanmasını söyle.
+- **Repo listele:** `systa_api_call` `GET /github/me/repos` — PAT'ın eriştiği repo'lar.
+- **Issue içe aktar (GitHub → SysTa talep):** `systa_api_call` `POST /github/me/import` — seçili repo'nun issue'larını kullanıcının KENDİ talepleri olarak içe aktarır (idempotent, createdBy=self). "şu repodan issue'ları SysTa'ya aktar / GitHub'dan talep aç" → bu. Mutating + canlı: hangi repo / kaç issue özetini göster, **onay al**.
+- **Talep push (SysTa → GitHub issue):** `systa_api_call` `POST /github/me/push` — kullanıcının talebini kendi repo'suna GitHub issue'su olarak gönderir/günceller (idempotent, node_id). Dış yan-etki (GitHub'a yazar) → **onay al**.
+
 ## Zincirleme & hata kurtarma (chaining & error recovery)
 
 SysTa returns structured errors. Recover deterministically instead of giving up.
@@ -222,7 +253,7 @@ SysTa returns structured errors. Recover deterministically instead of giving up.
    - Retry once after a fix. If it fails again with the same field, surface it to the user rather than looping.
 2. **`UNEXPECTED_FILE_FIELD` / `UNKNOWN_PARAM`** — you sent a flag/field the endpoint doesn't accept. Re-check with `describe_endpoint` and drop it. (Web/UI-only fields aren't valid on the API surface.)
 3. **`404` on a `:requestNumber` / `:id`** — the handle didn't resolve. Run the matching list/search (`list_requests`, `list_projects`, or `systa_api_call` `GET /users?search=`, `GET /tags/search`) to map name/number → id, then retry. Never hard-code an id.
-4. **ID resolution chain (general).** Most mutations need an id the user gave you as a name. There are NO dedicated lookup tools — use `systa_api_call`: company → `GET /companies`, team → `GET /teams` (name→`teamCode`), user → `GET /users?search=` (name→`userId`, "ben/bana"→self via who-am-i), status → `GET /statuses` (name→`statusId`), tag → `GET /tags/search`, board → request's kanban hierarchy (`get_request_board`; requestId→`boardId`→`columnId`). Resolve first, act second.
+4. **ID resolution chain (general).** Most mutations need an id the user gave you as a name. Use dedicated tools when available (each returns rows with `{id, name/key}`); fall back to `systa_api_call` for kinds not covered. **company / team / department / organization / category / status → `list_lookup(kind:'<kind>', search:'<name>')`** — one tool covers six reference entities. **user → `resolve_user_by_name(name)`** — returns `{userId}` on unique match or `{ambiguity:true, candidates}` on multi-match (ASK user, do NOT auto-pick); `list_users(search, ...)` for browsing. "ben/bana" → `list_capabilities.user.id`. tag → `systa_api_call GET /tags/search`. board → request's kanban hierarchy (`get_request_board`; requestId→boardId→columnId). Resolve first, act second.
 5. **`401/403`** — expired or out-of-scope key. Don't retry blindly; tell the user the auth/permission problem (in their language) and stop. For `403 permission`, name the capability the key lacks; don't attempt a privilege workaround.
 6. **`409 conflict`** (optimistic concurrency on cards/edits) — re-read the entity to get the latest `updatedAt`, then retry the mutation once with the fresh value; warn the user only if it conflicts again.
 7. **Dual-path "list vs create" endpoints** (e.g. `POST /api/sla/definitions`, `POST /api/sla/standby-configs`) — an empty/filter-only body lists; a full body creates. Choose the body shape that matches the intent; don't accidentally create when the user asked to list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systa-mcp",
-  "version": "1.0.8",
+  "version": "1.1.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",
@@ -13,7 +13,9 @@
     "README.md"
   ],
   "scripts": {
-    "start": "node server.js"
+    "start": "node server.js",
+    "check:version-sync": "node scripts/check-version-sync.js",
+    "prepublishOnly": "node scripts/check-version-sync.js"
   },
   "engines": {
     "node": ">=18"

package/server.js

@@ -420,12 +420,72 @@ const shapeOneModule = (caps, target) => {
   };
 };
 
+// list_requests: 'openOnly' + 'overdue' both need the NON-final status ids -- GET
+// /requests accepts statusId as an array, but has no excludeStatusIds. Fetch
+// /statuses once and INCLUDE the non-final ones.
+const resolveListRequestsStatusFilter = async (args) => {
+  const wantOnlyOpen = args.openOnly || args.overdue === true;
+  if (!wantOnlyOpen) {
+    return args.statusId;
+  }
+  const st = await systaFetch('GET', '/statuses').catch(() => null);
+  const rows = st && st.ok ? (st.data && (st.data.data || st.data)) || [] : [];
+  const openIds = (Array.isArray(rows) ? rows : []).filter((s) => s && !s.isFinal).map((s) => s.id);
+  return openIds.length > 0 ? openIds : args.statusId;
+};
+
+// list_requests: assemble the querystring the backend querySchema.js normalizes.
+// Bracket-form (deadlineDaysRemaining[operator]) and comma-separated arrays are
+// canonical for that validator; url.searchParams encodes brackets literally.
+const buildListRequestsQuery = (args, statusId) => {
+  const query = {
+    limit: args.limit ?? 20,
+    offset: args.offset,
+    search: args.search,
+    statusId,
+    assignedTo: args.assignedTo,
+    companyId: args.companyId,
+    categoryId: args.categoryId,
+    departmentId: args.departmentId,
+    priority: args.priority,
+    // Blind-AI-friendly default: return the lightweight 'summary' shape
+    // (~1KB/row) unless the caller explicitly asks for detail/full.
+    fields: args.fields ?? 'summary',
+  };
+  if (Array.isArray(args.searchIn) && args.searchIn.length > 0) {
+    query.searchIn = args.searchIn.join(',');
+  }
+  if (Array.isArray(args.slaStatus) && args.slaStatus.length > 0) {
+    query.slaStatus = args.slaStatus.join(',');
+  }
+  if (args.slaBreached === true) {
+    query.slaBreached = true;
+  }
+  if (typeof args.hasAttachments === 'boolean') {
+    query.hasAttachments = args.hasAttachments;
+  }
+  if (args.deadlineFrom) {
+    query.deadlineFrom = args.deadlineFrom;
+  }
+  if (args.deadlineTo) {
+    query.deadlineTo = args.deadlineTo;
+  }
+  if (args.overdue === true) {
+    query['deadlineDaysRemaining[operator]'] = 'lt';
+    query['deadlineDaysRemaining[value]'] = 0;
+  } else if (typeof args.deadlineWithinDays === 'number') {
+    query['deadlineDaysRemaining[operator]'] = 'lte';
+    query['deadlineDaysRemaining[value]'] = args.deadlineWithinDays;
+  }
+  return query;
+};
+
 // ── Tool definitions ─────────────────────────────────────────────────────────
 const TOOLS = [
   {
     name: 'list_requests',
     description:
-      'List/search SysTa requests (talepler) with pagination and rich filters: status, assignee, company, category, department, priority, free-text. "uzerimdeki acik isler / my open work" => assignedTo=<me> (resolve via list_capabilities user.id) + openOnly:true (one call — excludes final/"Tamamlandi" statuses automatically). Multiple statuses: statusId can be an array [1,3,5]. Returns only requests the API key scope permits. For filters beyond these, use systa_api_call GET /requests (this endpoint rejects unknown params with a 400 naming the valid set).',
+      "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).",
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -437,7 +497,29 @@ const TOOLS = [
           description: 'Page size (1-100, default 20)',
         },
         offset: { type: 'integer', minimum: 0, description: 'Pagination offset' },
-        search: { type: 'string', description: 'Free-text search' },
+        search: {
+          type: 'string',
+          description:
+            'Free-text; by default matches title, requestNumber, description, externalRef. For ATANAN (assignee) name lookup use resolve_user_by_name first, then filter by assignedTo. Broaden matching via searchIn.',
+        },
+        searchIn: {
+          type: 'array',
+          items: {
+            type: 'string',
+            enum: [
+              'title',
+              'description',
+              'requestnumber',
+              'externalref',
+              'category',
+              'creator',
+              'assignee',
+              'comments',
+            ],
+          },
+          description:
+            'Expand which fields the search string is matched against (default: title+description+requestnumber+externalref).',
+        },
         statusId: {
           type: ['integer', 'array'],
           items: { type: 'integer' },
@@ -455,37 +537,212 @@ const TOOLS = [
         companyId: { type: 'integer', description: 'Filter by company id' },
         categoryId: { type: 'integer', description: 'Filter by category id' },
         departmentId: { type: 'integer', description: 'Filter by department id' },
-        priority: { type: 'string', description: 'Filter by priority key/level' },
+        priority: {
+          type: 'string',
+          enum: ['low', 'normal', 'high', 'urgent', 'critical'],
+          description: 'Filter by priority key/level',
+        },
+        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.',
+        },
+        slaStatus: {
+          type: 'array',
+          items: { type: 'string', enum: ['active', 'paused', 'completed', 'breached'] },
+          description: 'SLA status filter (multi-value). Backend accepts comma-separated string.',
+        },
+        slaBreached: {
+          type: 'boolean',
+          description: 'true => only requests whose SLA has been breached.',
+        },
+        hasAttachments: {
+          type: 'boolean',
+          description:
+            'true => only requests with at least one active (non-deleted) top-level file attachment (files_table.request_id). Note: comment attachments and kanban card attachments live under separate tables -- this filter targets request-level uploads. Combine with fileCount>0 on the response for the same effect. Response row already carries fileCount so client-side filtering is possible on smaller pages.',
+        },
+        deadlineFrom: {
+          type: 'string',
+          description: 'Deadline >= this date (YYYY-MM-DD).',
+        },
+        deadlineTo: {
+          type: 'string',
+          description: 'Deadline <= this date (YYYY-MM-DD).',
+        },
+        deadlineWithinDays: {
+          type: 'integer',
+          description:
+            'Deadline within N days from now (i.e. deadlineDaysRemaining[operator]=lte,value=N).',
+        },
+        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).",
+        },
       },
     },
     handler: async (args) => {
-      let statusId = args.statusId;
-      // openOnly: resolve the NON-final status ids and filter to them. GET /requests
-      // accepts statusId as an array (validator normalizes a comma list); it does NOT
-      // support excludeStatusIds, so we INCLUDE the open ones rather than exclude final.
-      if (args.openOnly) {
-        const st = await systaFetch('GET', '/statuses').catch(() => null);
-        const rows = st && st.ok ? (st.data && (st.data.data || st.data)) || [] : [];
-        const openIds = (Array.isArray(rows) ? rows : [])
-          .filter((s) => s && !s.isFinal)
-          .map((s) => s.id);
-        if (openIds.length > 0) {
-          statusId = openIds;
-        }
-      }
-      return systaFetch('GET', '/requests', {
+      const statusId = await resolveListRequestsStatusFilter(args);
+      const query = buildListRequestsQuery(args, statusId);
+      return systaFetch('GET', '/requests', { query });
+    },
+  },
+  {
+    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).',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        search: {
+          type: 'string',
+          description: 'Free-text search over fullName/email/username (case-insensitive).',
+        },
+        companyId: { type: 'integer', description: 'Filter by company id' },
+        departmentId: { type: 'integer', description: 'Filter by department id' },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 100,
+          description: 'Page size (1-100, default 20)',
+        },
+        offset: { type: 'integer', minimum: 0, description: 'Pagination offset' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', '/users', {
         query: {
-          limit: args.limit ?? 20,
-          offset: args.offset,
           search: args.search,
-          statusId,
-          assignedTo: args.assignedTo,
           companyId: args.companyId,
-          categoryId: args.categoryId,
           departmentId: args.departmentId,
-          priority: args.priority,
+          limit: args.limit ?? 20,
+          offset: args.offset,
+        },
+      }),
+  },
+  {
+    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).",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Person name to resolve (partial match allowed)' },
+        companyId: {
+          type: 'integer',
+          description: 'Restrict search to a specific company (optional)',
         },
+      },
+    },
+    handler: async (args) => {
+      const res = await systaFetch('GET', '/users', {
+        query: { search: args.name, companyId: args.companyId, limit: 10 },
       });
+      if (!res.ok) {
+        return res;
+      }
+      const users =
+        res.data?.data?.users || res.data?.data?.items || res.data?.data || res.data || [];
+      const arr = Array.isArray(users) ? users : [];
+      const trimmed = String(args.name).trim().toLowerCase();
+      const exact = arr.filter(
+        (u) =>
+          String(u.fullName || '')
+            .trim()
+            .toLowerCase() === trimmed,
+      );
+      const pool = exact.length > 0 ? exact : arr;
+      if (pool.length === 0) {
+        return {
+          status: 200,
+          ok: true,
+          data: {
+            success: true,
+            data: {
+              matched: false,
+              hint: `No user found matching "${args.name}". Ask the user for the full name or a different spelling.`,
+              candidates: [],
+            },
+          },
+        };
+      }
+      if (pool.length === 1) {
+        const u = pool[0];
+        return {
+          status: 200,
+          ok: true,
+          data: {
+            success: true,
+            data: {
+              matched: true,
+              ambiguity: false,
+              userId: u.id,
+              fullName: u.fullName,
+              companyName: u.companyName || null,
+              departmentName: u.departmentName || null,
+            },
+          },
+        };
+      }
+      return {
+        status: 200,
+        ok: true,
+        data: {
+          success: true,
+          data: {
+            matched: true,
+            ambiguity: true,
+            hint: `Multiple users matched "${args.name}"; ASK the user which one -- do not auto-pick.`,
+            candidates: pool.slice(0, 10).map((u) => ({
+              id: u.id,
+              fullName: u.fullName,
+              email: u.email || null,
+              companyName: u.companyName || null,
+              departmentName: u.departmentName || null,
+            })),
+          },
+        },
+      };
+    },
+  },
+  {
+    name: 'bulk_update_requests',
+    description:
+      "Update MULTIPLE SysTa requests in ONE call (topluca guncelle) -- wraps PUT /api/requests/bulk. Use for 'these 5 talepler'i kritik yap' / 'set assignedTo to X for #189, #190, #191'. Provide requestIds (an array of numeric request ids/numbers) and updates (a partial field set applied to ALL of them). Do NOT loop calling update_request -- one bulk call is atomic per group and faster. If you need DIFFERENT updates per request, call bulk once per group. After success the response returns a batchId -- pass it to systa_api_call POST /requests/bulk/undo to revert if needed.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestIds', 'updates'],
+      properties: {
+        requestIds: {
+          type: 'array',
+          items: { type: 'integer' },
+          minItems: 1,
+          maxItems: 500,
+          description: 'Request numbers to update (1-500).',
+        },
+        updates: {
+          type: 'object',
+          additionalProperties: true,
+          description:
+            'Partial fields applied to every request in requestIds: statusId, assignedTo, priority, deadline, categoryId, departmentId, projectId, estimatedEffort (DAYS), personDay (DAYS), plannedStartDate, plannedEndDate, description, title.',
+        },
+        reason: {
+          type: 'string',
+          description: 'Optional audit reason (why the bulk change).',
+        },
+      },
+    },
+    handler: (args) => {
+      const body = { requestIds: args.requestIds, updates: args.updates };
+      if (args.reason) {
+        body.reason = args.reason;
+      }
+      return systaFetch('PUT', '/requests/bulk', { body });
     },
   },
   {
@@ -508,9 +765,128 @@ const TOOLS = [
       return systaFetch('GET', `/requests/${encodeURIComponent(rn)}`);
     },
   },
+  {
+    name: 'list_request_files',
+    description:
+      'List the ATTACHMENTS (dosya ekleri) of a SysTa request (GET /requests/:requestNumber/files). Returns {id, fileName, fileType, fileSize, uploadedAt, uploadedBy}. Use these fileIds with download_request_file to fetch content. NOTE: request-level attachments are only ONE of the file sources in SysTa -- comment attachments (in comments[].fileIds) and kanban card attachments live separately (see download_request_file for the full source list).',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestNumber'],
+      properties: {
+        requestNumber: { type: 'integer', description: 'Request number' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', `/requests/${encodeURIComponent(args.requestNumber)}/files`),
+  },
+  {
+    name: 'list_request_comments',
+    description:
+      "List the COMMENTS (yorumlar) of a SysTa request (GET /requests/:requestNumber/comments). Returns each comment's text/JSON, author, timestamp AND fileIds[] (attachment ids on the comment). The request's DESCRIPTION is materialized as comment #1 (commentNo=1). Comment attachments are a common file source -- use fileIds[] with download_request_file. Pagination via limit/offset if supported by the backend.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestNumber'],
+      properties: {
+        requestNumber: { type: 'integer', description: 'Request number' },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 100,
+          description: 'Page size',
+        },
+        offset: { type: 'integer', minimum: 0, description: 'Pagination offset' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', `/requests/${encodeURIComponent(args.requestNumber)}/comments`, {
+        query: { limit: args.limit, offset: args.offset },
+      }),
+  },
+  {
+    name: 'list_request_history',
+    description:
+      "List the CHANGE HISTORY / AUDIT LOG (degisiklik gecmisi / denetim) of a SysTa request (GET /requests/:requestNumber/history). Returns each change with actor, timestamp, field, oldValue, newValue. This is SysTa's per-entity audit trail -- there is no single 'audit log' endpoint. Use for 'X talebinde neler olmus / who changed the status'.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestNumber'],
+      properties: {
+        requestNumber: { type: 'integer', description: 'Request number' },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 100,
+          description: 'Page size',
+        },
+        offset: { type: 'integer', minimum: 0, description: 'Pagination offset' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', `/requests/${encodeURIComponent(args.requestNumber)}/history`, {
+        query: { limit: args.limit, offset: args.offset },
+      }),
+  },
+  {
+    name: 'list_lookup',
+    description:
+      "Unified id-resolution / lookup tool for reference entities (company / team / department / organization / category / status). Wraps the per-kind GET endpoints in ONE tool so blind AIs don't juggle 6 separate list tools. Call BEFORE create_request/update_request when you need to turn a NAME into an id ('Atlas Sigorta' -> companyId, 'Hata' -> categoryId, 'Test Ediliyor' -> statusId). Returns rows with {id, name/key} for the chosen kind. For USERS use resolve_user_by_name (name ambiguity handling is different).",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind'],
+      properties: {
+        kind: {
+          type: 'string',
+          enum: ['company', 'team', 'department', 'organization', 'category', 'status'],
+          description: 'Which reference entity to look up',
+        },
+        search: {
+          type: 'string',
+          description: 'Free-text search (name/code contains)',
+        },
+        companyId: {
+          type: 'integer',
+          description:
+            'Scope organization/department lookups to a specific company (ignored for others)',
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 100,
+          description: 'Page size (default 20)',
+        },
+      },
+    },
+    handler: (args) => {
+      const KIND_TO_PATH = {
+        company: '/companies',
+        team: '/teams',
+        department: '/departments',
+        organization: '/organizations',
+        category: '/categories',
+        status: '/statuses',
+      };
+      const path = KIND_TO_PATH[args.kind];
+      if (!path) {
+        throw new Error(`list_lookup: unknown kind '${args.kind}'`);
+      }
+      const query = {
+        search: args.search,
+        limit: args.limit ?? 20,
+      };
+      // company scoping only makes sense for org unit hierarchies.
+      if (args.companyId != null && (args.kind === 'department' || args.kind === 'organization')) {
+        query.companyId = args.companyId;
+      }
+      return systaFetch('GET', path, { query });
+    },
+  },
   {
     name: 'list_projects',
-    description: 'List SysTa projects (projeler). Returns only projects the API key scope permits.',
+    description:
+      'List/search SysTa projects (projeler) with pagination and filters. Project hierarchy: a project can have a parent_project_id (alt proje / sub-project). Filter to a subtree with parentProjectId=<id> (immediate children). NOTE: there is no root-only filter yet server-side; if you need only root projects, filter the response by projects with parentProjectId==null. Returns only projects the API key scope permits.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -522,10 +898,34 @@ const TOOLS = [
           description: 'Page size (1-100, default 20)',
         },
         offset: { type: 'integer', minimum: 0, description: 'Pagination offset' },
+        search: { type: 'string', description: 'Free-text search (project name/code/description)' },
+        companyId: { type: 'integer', description: 'Filter by company id' },
+        parentProjectId: {
+          type: 'integer',
+          description: 'Filter to the immediate children of this parent project',
+        },
+        status: {
+          type: 'string',
+          enum: ['active', 'passive', 'cancelled', 'completed'],
+          description: 'Filter by project lifecycle status',
+        },
+        sortBy: { type: 'string', description: 'Sort field (see project list docs)' },
+        sortOrder: { type: 'string', enum: ['asc', 'desc'], description: 'Sort direction' },
       },
     },
     handler: (args) =>
-      systaFetch('GET', '/projects', { query: { limit: args.limit ?? 20, offset: args.offset } }),
+      systaFetch('GET', '/projects', {
+        query: {
+          limit: args.limit ?? 20,
+          offset: args.offset,
+          search: args.search,
+          companyId: args.companyId,
+          parentProjectId: args.parentProjectId,
+          status: args.status,
+          sortBy: args.sortBy,
+          sortOrder: args.sortOrder,
+        },
+      }),
   },
   {
     name: 'create_request',
@@ -564,27 +964,72 @@ const TOOLS = [
           description:
             'Organization-unit id (optional; may be required by the active form; must belong to companyId)',
         },
+        departmentId: { type: 'integer', description: 'Department id (optional)' },
+        projectId: { type: 'integer', description: 'Link to a project (optional)' },
+        priority: {
+          type: 'string',
+          enum: ['low', 'normal', 'high', 'urgent', 'critical'],
+          description: "Priority key. Defaults to backend default (typically 'normal').",
+        },
+        deadline: {
+          type: 'string',
+          description: 'Deadline (YYYY-MM-DD or ISO-8601 datetime)',
+        },
+        plannedStartDate: {
+          type: 'string',
+          description: 'Planned start (YYYY-MM-DD). Must be <= plannedEndDate.',
+        },
+        plannedEndDate: {
+          type: 'string',
+          description: 'Planned end (YYYY-MM-DD). Must be >= plannedStartDate.',
+        },
+        estimatedEffort: {
+          type: 'number',
+          minimum: 0,
+          description:
+            "Estimated effort in CANONICAL DAYS (person-days). If user says 'N hours' divide by list_capabilities.effortPolicy.hoursPerDay BEFORE writing.",
+        },
+        personDay: {
+          type: 'number',
+          minimum: 0,
+          description: 'Person-day scoring in CANONICAL DAYS.',
+        },
       },
     },
-    handler: (args) =>
-      systaFetch('POST', '/requests', {
-        body: {
-          title: args.title,
-          description: args.description ?? '',
-          companyId: args.companyId,
-          statusId: args.statusId,
-          channel: args.channel ?? 'API',
-          ...(args.assignedTo != null ? { assignedTo: args.assignedTo } : {}),
-          ...(args.assignedTeams != null ? { assignedTeams: args.assignedTeams } : {}),
-          ...(args.categoryId != null ? { categoryId: args.categoryId } : {}),
-          ...(args.organizationId != null ? { organizationId: args.organizationId } : {}),
-        },
-      }),
+    handler: (args) => {
+      const body = {
+        title: args.title,
+        description: args.description ?? '',
+        companyId: args.companyId,
+        statusId: args.statusId,
+        channel: args.channel ?? 'API',
+      };
+      const passthrough = [
+        'assignedTo',
+        'assignedTeams',
+        'categoryId',
+        'organizationId',
+        'departmentId',
+        'projectId',
+        'priority',
+        'deadline',
+        'plannedStartDate',
+        'plannedEndDate',
+        'estimatedEffort',
+        'personDay',
+      ];
+      for (const key of passthrough) {
+        if (args[key] !== undefined && args[key] !== null) {
+          body[key] = args[key];
+        }
+      }
+      return systaFetch('POST', '/requests', { body });
+    },
   },
   {
     name: 'prepare_create_request',
     description:
-      'Proactively fetch everything create_request needs for a company: the ACTIVE request form\'s required system fields PLUS valid id options (statuses, categories, organizations, departments). Call this FIRST whenever the user wants to "talep ac / open a request" so you fill categoryId/organizationId/statusId up front and avoid the 400 VALIDATION_FAILED roundtrip. Returns requiredFields[] and options{statusId,categoryId,organizationId,departmentId}. statusId options carry isFinal (true => a "tamamla/kapat" status). companyId is required (org/department options are scoped to it). A missing option list means that lookup is out of this key scope -- ask the user or use systa_api_call.',
+      'Proactively fetch everything create_request needs for a company: the ACTIVE request form\'s required system fields PLUS valid id options (statuses, categories, organizations, departments). Call this FIRST whenever the user wants to "talep ac / open a request" so you fill categoryId/organizationId/statusId up front and avoid the 400 VALIDATION_FAILED roundtrip. Returns requiredFields[] and options{statusId,categoryId,organizationId,departmentId}. statusId options carry isFinal (true => a "tamamla/kapat" status). companyId is required (org/department options are scoped to it). NOTE ON companyId: this is the MUSTERI (client) company the request is FOR -- often DIFFERENT from your own user.companyId (which is the internal handler company). If the user has not stated a company, resolve by name (systa_api_call GET /companies?search=...) or ASK the user; do NOT default to user.companyId or pick one from the list at random. A missing option list means that lookup is out of this key scope -- ask the user or use systa_api_call.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -748,17 +1193,44 @@ const TOOLS = [
       });
     },
   },
+  {
+    name: 'list_allowed_transitions',
+    description:
+      "Preview the target statuses the request's CURRENT status is allowed to move to (durum gecisi onizle). SysTa restricts status transitions by workflow rules (category/company/department/priority scoped); calling this BEFORE change_request_status avoids a 400 TRANSITION_NOT_ALLOWED round-trip and lets you map a natural-language target ('test asamasi', 'tamamla', 'yeniden ac') to a specific statusId / statusKey from the returned list. Wraps GET /requests/:requestNumber/allowed-transitions.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestNumber'],
+      properties: {
+        requestNumber: {
+          type: 'integer',
+          description: "Request number whose current status's allowed transitions to preview",
+        },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', `/requests/${encodeURIComponent(args.requestNumber)}/allowed-transitions`),
+  },
   {
     name: 'change_request_status',
     description:
-      'Move a SysTa request to a target status (durum degistir / tamamla / kapat / yeniden ac), optionally with a closing comment. Resolve the target statusId by NAME first (list_capabilities or systa_api_call GET /statuses) -- do NOT guess the id. "tamamla/kapat" => a final status; "yeniden ac" => a non-final one. A given comment is posted right after the transition (plain text, auto-wrapped to TipTap). A status change may trigger a workflow gate/approval -- if the API returns such an error, read it and act, do not retry blindly.',
+      'Move a SysTa request to a target status (durum degistir / tamamla / kapat / yeniden ac), optionally with a closing comment. BEFORE calling, use list_allowed_transitions(requestNumber) to see valid target statuses -- transition rules restrict which statuses are reachable from the current one. Give EITHER statusId OR statusKey (statusKey resolves via GET /statuses; a natural-language user phrase like "test asamasi" maps to statusKey~test). "tamamla/kapat" => a final status (isFinal=true); "yeniden ac" => a non-final one. A given comment is posted right after the transition (plain text, auto-wrapped to TipTap). A status change may trigger a workflow gate/approval -- if the API returns 400 TRANSITION_NOT_ALLOWED read the error.details, pick a valid target and retry; do NOT retry blindly.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
-      required: ['requestNumber', 'statusId'],
+      required: ['requestNumber'],
       properties: {
         requestNumber: { type: 'integer', description: 'Request number to transition' },
-        statusId: { type: 'integer', description: 'Target status id (resolve by name first)' },
+        statusId: {
+          type: 'integer',
+          description:
+            'Target status id (from list_allowed_transitions). Provide statusId OR statusKey.',
+        },
+        statusKey: {
+          type: 'string',
+          description:
+            "Target status key (e.g. 'completed', 'testing', 'in_progress'). Provide statusId OR statusKey.",
+        },
         comment: {
           type: 'string',
           description: 'Optional closing/transition comment (plain text)',
@@ -766,8 +1238,45 @@ const TOOLS = [
       },
     },
     handler: async (args) => {
+      let statusId = args.statusId ?? null;
+      if (statusId == null && args.statusKey) {
+        // Resolve statusKey -> statusId via allowed-transitions (workflow-aware:
+        // prefers targets legal from the current status) with a fallback to the
+        // global statuses list if allowed-transitions doesn't match the key.
+        const allowedRes = await systaFetch(
+          'GET',
+          `/requests/${encodeURIComponent(args.requestNumber)}/allowed-transitions`,
+        );
+        const allowed = allowedRes?.data?.data?.allowedTransitions || [];
+        const hit = allowed.find(
+          (t) => String(t.statusKey || '').toLowerCase() === String(args.statusKey).toLowerCase(),
+        );
+        if (hit) {
+          statusId = hit.id ?? hit.statusId;
+        }
+        if (statusId == null) {
+          const statusesRes = await systaFetch('GET', '/statuses');
+          const all = statusesRes?.data?.data?.statuses || statusesRes?.data?.data || [];
+          const g = all.find(
+            (s) => String(s.statusKey || '').toLowerCase() === String(args.statusKey).toLowerCase(),
+          );
+          if (g) {
+            statusId = g.id;
+          }
+        }
+        if (statusId == null) {
+          throw new Error(
+            `change_request_status: statusKey='${args.statusKey}' could not be resolved -- call list_allowed_transitions to see valid keys`,
+          );
+        }
+      }
+      if (statusId == null) {
+        throw new Error(
+          'change_request_status: provide statusId or statusKey (see list_allowed_transitions)',
+        );
+      }
       const res = await systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, {
-        body: { statusId: args.statusId },
+        body: { statusId },
       });
       if (args.comment && String(args.comment).trim()) {
         const doc = {
@@ -784,7 +1293,7 @@ const TOOLS = [
   {
     name: 'update_request',
     description:
-      'Update fields of an existing SysTa request (talebi guncelle/duzenle) -- PARTIAL: only the fields you pass change. For STATUS use change_request_status, for ASSIGNEE use assign_request, for COMMENTS use add_request_comment (focused intents). Use this for title/description/category/department/priority/deadline/project edits. Resolve categoryId/departmentId/projectId by name first.',
+      "Update fields of an existing SysTa request (talebi guncelle/duzenle) -- PARTIAL: only the fields you pass change. For STATUS use change_request_status, for ASSIGNEE use assign_request, for COMMENTS use add_request_comment (focused intents). Use this for title/description/category/department/priority/deadline/planned dates/effort/project edits. Resolve categoryId/departmentId/projectId by name first. estimatedEffort/actualEffort/personDay are in CANONICAL DAYS -- if the user says 'N hours', divide by list_capabilities.effortPolicy.hoursPerDay BEFORE writing.",
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -796,8 +1305,36 @@ const TOOLS = [
         categoryId: { type: 'integer', description: 'Category id (resolve by name)' },
         departmentId: { type: 'integer', description: 'Department id' },
         projectId: { type: 'integer', description: 'Link to project id' },
-        priority: { type: 'string', description: 'Priority key/level' },
-        deadline: { type: 'string', description: 'Deadline (ISO date)' },
+        priority: {
+          type: 'string',
+          enum: ['low', 'normal', 'high', 'urgent', 'critical'],
+          description: 'Priority key/level',
+        },
+        deadline: { type: 'string', description: 'Deadline (ISO date YYYY-MM-DD or ISO-8601)' },
+        plannedStartDate: {
+          type: 'string',
+          description: 'Planned start (YYYY-MM-DD). Must be <= plannedEndDate.',
+        },
+        plannedEndDate: {
+          type: 'string',
+          description: 'Planned end (YYYY-MM-DD). Must be >= plannedStartDate.',
+        },
+        estimatedEffort: {
+          type: 'number',
+          minimum: 0,
+          description:
+            "Estimated effort in CANONICAL DAYS (person-days). '8 saat' => 8 / hoursPerDay.",
+        },
+        actualEffort: {
+          type: 'number',
+          minimum: 0,
+          description: 'Actual effort in CANONICAL DAYS (person-days).',
+        },
+        personDay: {
+          type: 'number',
+          minimum: 0,
+          description: 'Person-day scoring in CANONICAL DAYS.',
+        },
       },
     },
     handler: (args) => {
@@ -839,10 +1376,43 @@ const TOOLS = [
       return systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, { body });
     },
   },
+  {
+    name: 'create_request_board',
+    description:
+      'Create the kanban task board (gorev panosu) for a SysTa request when it does NOT yet have one. Call THIS when get_request_board or manage_request_card returns 404 KANBAN_BOARD_NOT_FOUND (code 2031) -- do not retry the read/manage call blindly. Optional templateId picks a preset column layout; without it a default column set is created. Discover templates with systa_api_call GET /task-boards/templates. After board create you can immediately use manage_request_card to add cards.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestId'],
+      properties: {
+        requestId: {
+          type: 'integer',
+          description: 'Request number to attach the board to',
+        },
+        templateId: {
+          type: 'integer',
+          description: 'Optional task-board template id (GET /task-boards/templates lists them)',
+        },
+        boardName: { type: 'string', description: 'Optional board display name' },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      if (args.templateId != null) {
+        body.templateId = args.templateId;
+      }
+      if (args.boardName) {
+        body.boardName = args.boardName;
+      }
+      return systaFetch('POST', `/requests/${encodeURIComponent(args.requestId)}/kanban`, {
+        body,
+      });
+    },
+  },
   {
     name: 'get_request_board',
     description:
-      "Read the kanban task board (gorev panosu) of a SysTa request: its columns and the cards in each. READ-only -- to add/edit a card use manage_request_card, to move/reorder use move_request_card; for the request's own fields/comments use get_request/add_request_comment. requestId is the request number.",
+      "Read the kanban task board (gorev panosu) of a SysTa request: its columns and the cards in each. READ-only -- to add/edit a card use manage_request_card, to move/reorder use move_request_card; for the request's own fields/comments use get_request/add_request_comment. requestId is the request number. If the response is 404 KANBAN_BOARD_NOT_FOUND (code 2031) the request has NO board yet -- call create_request_board(requestId) FIRST, then retry.",
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -871,7 +1441,7 @@ const TOOLS = [
   {
     name: 'manage_request_card',
     description:
-      'Create a card in a board column (requestId + columnId + cardTitle) OR update an existing card (requestId + cardId, partial fields). Does NOT move/reorder cards -- use move_request_card; read ids first with get_request_board. Resolve columnId and assignee ids before calling.',
+      'Create a card in a board column (requestId + columnId + cardTitle) OR update an existing card (requestId + cardId, partial fields). Does NOT move/reorder cards -- use move_request_card; read ids first with get_request_board. Resolve columnId and assignee ids before calling. PREREQUISITE: the request MUST have a kanban board -- if get_request_board or this call returns 404 KANBAN_BOARD_NOT_FOUND (code 2031), call create_request_board(requestId) first, then retry.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -892,6 +1462,12 @@ const TOOLS = [
         },
         assignedTeams: { type: 'array', items: { type: 'integer' } },
         priority: { type: 'string', description: 'low|normal|high|urgent|critical' },
+        estimatedEffort: {
+          type: 'number',
+          minimum: 0,
+          description:
+            "Estimated effort in CANONICAL DAYS (person-days). If user says 'N hours' divide by list_capabilities.effortPolicy.hoursPerDay BEFORE writing.",
+        },
         tags: { type: 'array', items: { type: 'string' } },
         deadline: { type: 'string', description: 'ISO-8601 datetime' },
         cardColor: { type: 'string', description: '#RRGGBB hex' },
@@ -1064,6 +1640,32 @@ const TOOLS = [
       return systaFetch('POST', '/projects', { body });
     },
   },
+  {
+    name: 'duplicate_project',
+    description:
+      "Clone/duplicate a SysTa project (POST /projects/:id/duplicate) -- copies the source project's DEFINITION (name, company/department/org, parent, dates, weight, planned effort, governance toggles) into a new project. Optional {newProjectName}. NOT COPIED: sub-projects, requests, board, milestones, snapshots, actual effort/progress -- these are start-fresh on the new project. Returns the new project's id/code. Requires the project.create scope.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['id'],
+      properties: {
+        id: { type: 'integer', description: 'Source project id to clone from' },
+        newProjectName: {
+          type: 'string',
+          description: "New project's name (optional; server appends '(Copy)' if omitted)",
+        },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      if (args.newProjectName) {
+        body.newProjectName = args.newProjectName;
+      }
+      return systaFetch('POST', `/projects/${encodeURIComponent(args.id)}/duplicate`, {
+        body,
+      });
+    },
+  },
   {
     name: 'get_project',
     description: 'Get one SysTa project (proje) by its numeric id, including sub-projects.',
@@ -1372,10 +1974,48 @@ const TOOLS = [
       }
     },
   },
+  {
+    name: 'create_plan_mode',
+    description:
+      "Create a plan mode / sprint scope (POST /plan/modes). A plan mode is the CONTAINER for a sprint's boards; create_plan_baseline then snapshots its live state. Boards is TECHNICALLY optional server-side but a mode WITHOUT boards produces empty baselines -- if you omit boards this tool auto-adds a single default board ({boardName:'Gorev Tahtasi'}) so create_plan_baseline works out of the box. Give boards[] explicitly when you want multiple boards or filterCriteria that pre-filters requests per board. Returns the created mode's id (use it for create_plan_baseline modeId).",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Mode / sprint name (min 1 char)' },
+        description: { type: 'string', description: 'Optional description' },
+        companyId: {
+          type: 'integer',
+          description: 'Scope to a specific company (optional)',
+        },
+        boards: {
+          type: 'array',
+          description:
+            'Boards for the mode. If omitted a single default board is inserted. Each board: {boardName, filterCriteria?, targetCriteria?, displayOrder?}.',
+          items: { type: 'object', additionalProperties: true },
+        },
+      },
+    },
+    handler: (args) => {
+      const body = { name: args.name };
+      if (args.description !== undefined) {
+        body.description = args.description;
+      }
+      if (args.companyId != null) {
+        body.companyId = args.companyId;
+      }
+      body.boards =
+        Array.isArray(args.boards) && args.boards.length > 0
+          ? args.boards
+          : [{ boardName: 'Görev Tahtası', displayOrder: 1 }];
+      return systaFetch('POST', '/plan/modes', { body });
+    },
+  },
   {
     name: 'create_plan_baseline',
     description:
-      'Create a plan baseline/snapshot for a plan mode (POST /plan/modes/:modeId/baselines). Omit boards -- the server snapshots the mode live state (built for AI clients with no board state). Returns baselineId for submit_plan_for_approval.',
+      'Create a plan baseline/snapshot for a plan mode (POST /plan/modes/:modeId/baselines). Omit boards -- the server snapshots the mode live state (built for AI clients with no board state). Returns baselineId for submit_plan_for_approval. modeId comes from create_plan_mode.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -1400,6 +2040,46 @@ const TOOLS = [
       });
     },
   },
+  {
+    name: 'get_plan_baseline',
+    description:
+      "Get a single plan baseline (GET /plan/baselines/:baselineId). Blind-AI-friendly: fields defaults to 'summary' which STRIPS snapshotData (can be ~800KB on real plans) and returns just metadata + counts (baselineName, totalCards, totalEffort, approvalStatus, periodStart/End, createdAt, hasSnapshot boolean). Pass fields:'full' ONLY when you truly need the raw board/card snapshot (rare). For 'ne degisti / snapshot fark' use compare_plan_baseline, NOT the raw snapshot.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['baselineId'],
+      properties: {
+        baselineId: { type: 'integer', description: 'Baseline id' },
+        fields: {
+          type: 'string',
+          enum: ['summary', 'full'],
+          description:
+            "Response profile. Default: 'summary' (snapshot omitted, metadata only). 'full' returns the raw snapshot_data (heavy).",
+        },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', `/plan/baselines/${encodeURIComponent(args.baselineId)}`, {
+        query: { fields: args.fields ?? 'summary' },
+      }),
+  },
+  {
+    name: 'compare_plan_baseline',
+    description:
+      "Compare a plan baseline snapshot (snapshot fark / baseline karsilastir) against the CURRENT board state (POST /plan/baselines/:baselineId/compare). Returns the diff (added/removed/changed cards, affected boards) WITHOUT streaming the raw baseline snapshot -- much smaller than GET /plan/baselines/:baselineId (which can be ~800KB). Use this whenever the user asks 'son snapshot ile bugunku durum arasindaki fark' / 'plani onceki halle karsilastir'. baselineId comes from create_plan_baseline or list_plan_baselines (systa_api_call GET /plan/baselines?modeId=). read_only.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['baselineId'],
+      properties: {
+        baselineId: { type: 'integer', description: 'Baseline id to compare against live state' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('POST', `/plan/baselines/${encodeURIComponent(args.baselineId)}/compare`, {
+        body: {},
+      }),
+  },
   {
     name: 'submit_plan_for_approval',
     description:
@@ -1714,7 +2394,7 @@ const TOOLS = [
   {
     name: 'querybuilder_describe_fields',
     description:
-      "Discover queryable fields for a reportType: mode 'fields' (metadata/fieldKeys), 'options' (filter value options), or 'suggest' (q search). Never invent field names -- read mode='fields' first.",
+      "Discover queryable fields for a reportType: mode 'fields' (metadata/fieldKeys), 'options' (filter value options), or 'suggest' (q search). Never invent field names -- read mode='fields' first. LARGE RESPONSE WARNING: mode='fields' can return 60KB+ (dozens of fields per reportType); if you are only looking for a common concept ('kapatilan/completed', 'atanan/assignee', 'kategori', 'tarih'), call mode='suggest' with a q term instead of dumping the whole list. Report reportType common fields: request→statusId/statusKey/completedAt/createdAt/priority/assignedTo/companyId; sla→slaStatus/breachedAt/dueAt; user→userId/isActive/isSuspended; project→statusId/lifecycle/healthScore. 'kapatilmis talep' = statusKey∈(completed,cancelled,rejected) OR isFinal=true (bkz. glossary 'kapatilmis talep').",
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -1855,10 +2535,21 @@ const TOOLS = [
   {
     name: 'download_request_file',
     description:
-      'Download a SysTa attachment (request/task-card/project file) to the LOCAL disk and ' +
+      'Download a SysTa attachment (any file the API key can access) to the LOCAL disk and ' +
       'return the saved path. Requires the "file.download" scope; all access checks run ' +
-      'server-side. fileId comes from file list endpoints (e.g. GET /requests/:n/files). ' +
-      'Saves into a temp directory unless savePath is given.',
+      'server-side. Saves into a temp directory unless savePath is given. ' +
+      'SysTa files live under SEVEN different sources -- fileId is resolved from ONE of these ' +
+      'list endpoints (most user-visible files are actually COMMENT or KANBAN attachments, not ' +
+      'top-level request attachments): ' +
+      '(1) request attachment: list_request_files(requestNumber) / GET /requests/:n/files, ' +
+      '(2) comment attachment: list_request_comments(requestNumber) -- each comment carries fileIds[], ' +
+      '(3) kanban card attachment: systa_api_call GET /requests/:reqId/kanban/cards/:cardId/files, ' +
+      '(4) kanban card comment attachment: systa_api_call GET /requests/:reqId/kanban/cards/:cardId/comments (comment.fileIds[]), ' +
+      '(5) project file: systa_api_call GET /projects/:id/files, ' +
+      '(6) sub-form submission attachment: systa_api_call GET /form-submissions/:id/files, ' +
+      '(7) announcement attachment: systa_api_call GET /announcements/:id. ' +
+      'If list_request_files returns empty, the request likely has NO top-level attachments ' +
+      'yet -- check comments (source 2) BEFORE concluding there is no file.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -2098,20 +2789,30 @@ const TOOL_MAP = new Map(TOOLS.map((tool) => [tool.name, tool]));
 const TOOL_REQUIRED_PERMISSION = {
   list_requests: 'request.read',
   get_request: 'request.tabs.general.view',
+  list_request_files: 'request.tabs.files.view',
+  list_request_comments: 'request.comment.read',
+  list_request_history: 'request.tabs.history.view',
+  list_lookup: 'request.read',
   list_projects: 'project.read',
+  list_users: 'user.read',
+  resolve_user_by_name: 'user.read',
   create_request: 'request.create',
   prepare_create_request: 'request.create',
   add_request_comment: 'request.comment.create',
   change_request_status: 'request.update',
+  list_allowed_transitions: 'request.read',
   update_request: 'request.update',
+  bulk_update_requests: 'request.update',
   assign_request: 'request.update',
   get_request_board: 'request.read',
+  create_request_board: 'request.update',
   manage_request_card: 'request.update',
   move_request_card: 'request.update',
   request_approval: 'request.approval.create',
   respond_to_approval: 'request.approval.respond',
   list_pending_approvals: 'request.approval.view',
   create_project: 'project.create',
+  duplicate_project: 'project.create',
   get_project: 'project.read',
   update_project: 'project.update',
   get_project_health: 'project.read',
@@ -2121,7 +2822,10 @@ const TOOL_REQUIRED_PERMISSION = {
   achieve_milestone: 'project.update',
   manage_project_stakeholders: 'project.update',
   manage_project_notes: 'project.update',
+  create_plan_mode: 'request.update',
   create_plan_baseline: 'request.update',
+  get_plan_baseline: 'request.read',
+  compare_plan_baseline: 'request.read',
   submit_plan_for_approval: 'plan.approval.submit',
   respond_to_plan_approval: 'plan.approval.review',
   get_plan_critical_path: 'request.read',