natureco-cli 5.6.45 → 5.6.46

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to NatureCo CLI will be documented in this file.
 
+## [5.6.46] - 2026-06-24 — "README OVERHAUL"
+
+### 📚 Documentation
+- **README.md full rewrite** — 5.6.x serisine uygun:
+  - Hero slogan: "Yapay Zekânın Gücü artık parmaklarının ucunda / Terminalin hızını NatureCo ile keşfet"
+  - ASCII art banner
+  - Node badge: `>=16.0.0` (package.json engines ile uyumlu)
+  - npm version, downloads, GitHub stars badge'leri
+  - Quick Start 4 adım: install → setup → chat → code
+  - 51 komut / 10 kategori, gerçek örnekler
+  - Discord `https://discord.gg/4FwumbWph`, Twitter `https://twitter.com/naturecoofficial`
+  - GitHub: `natureco-official/natureco-cli`
+  - Karşılaştırma tablosu (Claude Code / Hermes / OpenClaw)
+  - 30s setup wizard tanıtımı
+
+### 🎯 Versiyon Notu
+- 5.6.45 → 5.6.46 (patch bump, README-only release)
+- Kod değişikliği yok, npm sayfası güncellendi
+- Yeni kullanıcılar README üzerinden kurulum yapabilir
+
+---
+
 ## [4.2.0] - 2026-06-22 — "LAUNCH READY"
 
 ### 🚀 Headline

package/README.md

@@ -528,8 +528,7 @@ natureco mcp add github npx -y @modelcontextprotocol/server-github
 - 📖 **Komut referansı:** [natureco.me/cli/commands](https://natureco.me/cli/commands)
 - 🎓 **Tutorial:** [natureco.me/cli/getting-started](https://natureco.me/cli/getting-started)
 - 🔧 **API:** [natureco.me/cli/api](https://natureco.me/cli/api)
-- 💬 **Discord topluluğu:** [discord.gg/natureco](https://discord.gg/natureco)
-- 📱 **Telegram grup:** [t.me/natureco](https://t.me/natureco)
+- 💬 **Discord topluluğu:** [discord.gg/4FwumbWph](https://discord.gg/4FwumbWph)
 - 🐦 **Twitter/X:** [@naturecoofficial](https://twitter.com/naturecoofficial)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "natureco-cli",
-  "version": "5.6.45",
+  "version": "5.6.46",
   "description": "OpenClaw'dan daha güvenli, daha hızlı, daha ucuz AI agent CLI. Multi-agent, self-evolving skills, audit log, maliyet optimizasyonu ve NatureCo platform-native.",
   "bin": {
     "natureco": "bin/natureco.js"

package/skills/caveman/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: cavecrew
+description: Token tasarrufu için subagent delegasyon karar rehberi. Ana thread cavecrew subagent'larına (investigator/builder/reviewer) ne zaman delege edeceğini bilir. Subagent çıktıları caveman-compressed formatta döner → %60 daha küçük context.
+metadata: {"natureco": {"requires": {"bins": []}, "os": ["darwin","linux","win32"]}}
+---
+
+# Cavecrew Skill (Token Tasarrufu Subagent Pattern)
+
+Subagent çıktıları main context'e aynen inject edilir. Vanilla Explore 2k token prose dönerse → 2k token harcarsın. Cavecrew ~700 token döner. 20 delegasyon = context bitme vs işi bitirme farkı.
+
+## Hangi Subagent Ne Zaman
+
+| İş | Kullan |
+|-----|-------|
+| "X nerede tanımlı / Y'yi kim çağırıyor / Z'nin kullanımları" | `cavecrew-investigator` |
+| Aynısı + mimari yorum | vanilla `Explore` |
+| Cerrahi edit, ≤2 dosya | `cavecrew-builder` |
+| Yeni feature / 3+ dosya / cross-cutting | Ana thread veya `feature-dev:code-architect` |
+| Diff/branch/file review (bug) | `cavecrew-reviewer` |
+| Derin code review (gerekçe + alternatifler) | vanilla `Code Reviewer` |
+| 1 satır cevap, zaten biliyorsun | Ana thread, subagent yok |
+
+**Kural:** 1/3 token istiyorsan → cavecrew. Prose istiyorsan → vanilla.
+
+## Output Formatları (Subagent sözleşmeleri)
+
+**`cavecrew-investigator`:**
+```
+<Header>:
+- path:line — `symbol` — kısa not
+totals: <sayım>.
+```
+veya `No match.`
+
+**`cavecrew-builder`:**
+```
+<path:line-range> — <change ≤10 kelime>.
+verified: <re-read OK | mismatch @ path:line>.
+```
+veya `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.`
+
+**`cavecrew-reviewer`:**
+```
+path:line: <emoji> <severity>: <problem>. <fix>.
+totals: N🔴 N🟡 N🔵 N❓
+```
+veya `No issues.`
+
+## Chaining (Sıralı Çağrı)
+
+**Locate → fix → verify** (en yaygın):
+1. `cavecrew-investigator` site listesi döner
+2. Ana thread 1-2 site seçer, `cavecrew-builder`'a path verir
+3. `cavecrew-reviewer` diff'i inceler
+
+**Parallel scout** (geniş investigation):
+Bir mesajda 2-3 `cavecrew-investigator` çağır (farklı açılar: defs/callers/tests). Ana thread'de topla.
+
+**Single-shot edit** (site zaten biliniyor):
+Investigator atla, direkt `cavecrew-builder`'a path:line ver.
+
+## YAPMA
+
+- `cavecrew-builder` → dosya bilinmiyorsa YAPMA. Önce investigator.
+- 5-dosya refactor'da `investigator → builder` chain YAPMA. Builder `too-big.` döner.
+- `cavecrew-reviewer`'dan "genel feedback" isteme YAPMA. Sadece findings.
+- Prose bekleme YAPMA. Cavecrew output yapısal, kuru. İnsan okuyacaksa paraphrase et.
+
+## Auto-clarity
+
+Security uyarıları, irreversible-action onayları — subagent'lar caveman'dan normal İngilizce'ye geçer. Sonra devam.

package/skills/caveman-compress/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: caveman-compress
+description: Doğal dil dosyalarını (CLAUDE.md, memory, todo, preferences) caveman formatına sıkıştırır. Token tasarrufu. Teknik içerik (kod, URL, path) korunur. /caveman-compress FILEPATH veya "compress memory file" tetikleyicisi.
+metadata: {"natureco": {"requires": {"bins": ["python3"]}, "os": ["darwin","linux","win32"]}}
+---
+
+# Caveman Compress Skill
+
+Doğal dil dosyalarını caveman-speak'e sıkıştır. Input token tasarrufu. Compressed dosya orijinalin yerine geçer. Backup `FILE.original.md` olarak saklanır.
+
+## Tetikleyici
+
+`/caveman-compress  filepath` veya "compress memory file" dediğinde.
+
+## Sıkıştırma Kuralları
+
+### ÇIKAR
+- Article: a, an, the
+- Filler: just, really, basically, actually, simply, essentially, generally
+- Pleasantries: "sure", "certainly", "of course", "happy to"
+- Hedging: "it might be worth", "you could consider"
+- Redundant: "in order to" → "to", "make sure to" → "ensure"
+- Connective fluff: "however", "furthermore", "additionally"
+
+### KORU (Asla değiştirme)
+- Kod blokları (fenced ``` ve indented)
+- Inline code (`backtick`)
+- URL'ler ve linkler (tam URL, markdown link)
+- File paths (`/src/components/...`)
+- Komutlar (`npm install`, `git commit`, `docker build`)
+- Teknik terimler (kütüphane, API, protokol isimleri)
+- Özel isimler (proje, kişi, şirket)
+- Tarihler, versiyon, numerik değerler
+- Env değişkenleri (`$HOME`, `NODE_ENV`)
+
+### YAPIYI KORU
+- Tüm markdown başlıkları (tam metin)
+- Bullet point hiyerarşisi (nesting)
+- Numaralı listeler (numaralar)
+- Tablolar (hücre metni sıkıştırılabilir, yapı korunur)
+- Frontmatter/YAML header
+
+### SIKIŞTIR
+- Kısa eş anlamlı: "big" not "extensive", "fix" not "implement a solution for"
+- Fragment OK: "Run tests before commit" not "You should always run tests before committing"
+- "you should", "make sure to", "remember to" → sadece eylemi söyle
+- Aynı şeyi söyleyen fazla bullet'ları birleştir
+- Birden fazla örnek aynı pattern'i gösteriyorsa bir tane bırak
+
+## KRİTİK KURAL
+
+```...``` içindeki her şey **TAM KORUNMALI**. Yapma:
+- comment silme
+- spacing kaldırma
+- satır sırası değiştirme
+- komut kısaltma
+- hiçbir şeyi basitleştirme
+
+Inline code (`...`) da tam korunmalı. Backtick içinde değişiklik yapma.
+
+## Pattern
+
+**ÖNCE:**
+> You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.
+
+**SONRA:**
+> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
+
+**ÖNCE:**
+> The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.
+
+**SONRA:**
+> Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.
+
+## Sınırlar
+
+- **Sadece** doğal dil dosyaları sıkıştır (.md, .txt, .typ, extensionless)
+- **Asla** değiştirme: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh
+- Karışık içerikte **sadece prose** kısımlarını sıkıştır
+- Emin değilsen → değiştirme
+- Backup `FILE.original.md` olarak saklanır, **asla onu sıkıştırma**

package/skills/code-refactoring/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: code-refactoring
+description: Clean code, SOLID prensipleri ve modern mühendislik pratikleri. Karmaşık kodu basitleştirmek, code smell'leri gidermek, testability artırmak istediğinde bu skill'i yükle.
+metadata: {"natureco": {"requires": {"bins": []}, "os": ["darwin","linux","win32"]}}
+---
+
+# Code Refactoring Skill
+
+Clean code, SOLID design patterns ve modern yazılım mühendisliği ile kod kalitesini artır.
+
+## Ne Zaman Kullan
+
+- Karmaşık, bakımı zor kodu refactor etmek
+- Duplikasyon, karmaşıklık, code smell azaltmak
+- Testability ve tasarım tutarlılığı artırmak
+- Modülleri yeni feature'ler için güvenle hazırlamak
+
+**Kullanma:** tek satırlık fix, change freeze, sadece dokümantasyon isteği varsa.
+
+## Talimatlar
+
+1. **Code smell'leri değerlendir:** duplikasyon, uzun fonksiyon, yüksek coupling
+2. **Refactor planı oluştur:** incremental adımlarla
+3. **Küçük dilimler halinde uygula** — davranış sabit kalmalı
+4. **Testleri güncelle** ve regression olmadığını doğrula
+
+## Extract Method (Pattern)
+
+```typescript
+// ÖNCE
+function processOrder(order: Order) {
+  // validate
+  if (!order.items.length) throw new Error('empty');
+  // compute total
+  let total = 0;
+  for (const item of order.items) {
+    total += item.price * item.quantity;
+  }
+  // save
+  db.save({ orderId: order.id, total });
+}
+
+// SONRA
+function processOrder(order: Order) {
+  validateOrder(order);
+  const total = computeTotal(order);
+  saveOrder(order, total);
+}
+```
+
+## SOLID Prensipleri
+
+- **S**ingle Responsibility — bir sınıf/fonksiyon tek bir değişim nedeni olmalı
+- **O**pen/Closed — extension için açık, modification için kapalı
+- **L**iskov Substitution — alt sınıflar üst sınıfların yerine geçebilmeli
+- **I**nterface Segregation — interface'ler küçük ve öz olmalı
+- **D**ependency Inversion — abstraction'lara bağımlı, concrete'lere değil
+
+## Code Smell Kategorileri
+
+| Smell | Tedavi |
+|-------|--------|
+| Long Method (>30 satır) | Extract Method |
+| Long Class | Extract Class |
+| Duplicate Code | Extract Method → call from both |
+| Long Parameter List (>4) | Parameter Object |
+| Divergent Change | Extract Class (her değişim için bir sınıf) |
+| Shotgun Surgery | Move Method, Move Field |
+| Feature Envy | Move Method (kendi verisini kullanan sınıfa) |
+| Data Clumps | Extract Class |
+| Primitive Obsession | Replace Type Code with Class |
+| Switch Statements | Replace Conditional with Polymorphism |
+| Parallel Inheritance | Move Method/Field |
+| Lazy Class | Inline Class |
+| Speculative Generality | Collapse Hierarchy |
+| Temporary Field | Extract Class |
+| Message Chains | Hide Delegate |
+| Middle Man | Remove Middle Man |
+| Inappropriate Intimacy | Move Method, Extract Class |
+| Alternative Classes with Different Interfaces | Rename Method, Move Method |
+| Refused Bequest | Replace Inheritance with Delegation |
+| Comments | Rename Method (kendi kendini açıklayan) |
+| Duplicated Code | Extract Method |
+
+## Output Format
+
+```
+## Issues
+- <code smell 1>: <path:line>
+- <code smell 2>: <path:line>
+
+## Plan
+1. <step 1: Extract Method from X to Y>
+2. <step 2: Rename Z to W>
+...
+
+## Changes
+- <path:line-range> — <change>
+
+## Tests
+- <verification step>
+```
+
+## Güvenlik
+
+- External davranışı explicit onay olmadan değiştirme
+- Diff'leri reviewable tut (küçük, atomic)
+- Test'ler her zaman geçmeli

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: frontend-design
+description: Dikkat çekici, kasıtlı görsel tasarım rehberi. Yeni UI inşa ederken veya mevcut olanı yeniden şekillendirirken. Estetik yön, tipografi ve template default'larından kaçınma.
+metadata: {"natureco": {"requires": {"bins": []}, "os": ["darwin","linux","win32"]}}
+---
+
+# Frontend Design Skill
+
+Template gibi görünmeyen, özgün UI tasarımı için rehber.
+
+## Temel Felsefe
+
+Sen kısa bir stüdyonun tasarım direktörüsün. Her projeye özgün bir görsel kimlik veriyorsun. Brief'i oku, pinle, sonra bilinçli seçimler yap.
+
+## Tasarım İlkeleri
+
+### Hero = Tez
+Sayfa, konunun dünyasındaki en karakteristik şeyle açılmalı. Headline, imaj, animasyon, live demo — brief'e en uygun olan.
+
+### Tipografi = Kişilik
+Display ve body font'ları bilinçli seç. Her projede aynı fontlara düşme. Type scale, weight, spacing — hepsi bilinçli.
+
+### Yapı = Bilgi
+Yapısal elementler (numara, divider, label) içeriğin gerçek yapısını kodlamalı, süs olmamalı. "01 / 02 / 03" gibi numaralar sadece gerçekten sıralı içerik varsa kullanılmalı.
+
+### Hareket = Bilinçli
+Animasyon her yerde değil, doğru yerde. Page-load sequence, scroll reveal, hover micro-interaction — orkestre edilmiş bir an, dağınık efektlerden iyidir.
+
+### Karmaşıklık = Vizyon
+Maximalist yönler detaylı işçilik ister. Minimal yönler spacing, type, detayda hassasiyet ister. İkisinde de elegance = vizyonu iyi uygulamak.
+
+## AI Default'larından Kaçın
+
+AI-generated design 3 cluster'da toplanır:
+1. **Cream (#F4F1EA) + serif display + terracotta accent**
+2. **Near-black + single bright accent (acid-green/vermilion)**
+3. **Broadsheet-style (hairline rules, zero border-radius, dense columns)**
+
+Bunlar legitimate ama **default**. Brief bunlardan birini isterse kullan, aksi halde default'a düşme.
+
+## Process: Brainstorm → Explore → Plan → Critique → Build → Critique Again
+
+### Pass 1: Plan
+
+Compact token sistemi oluştur:
+- **Color:** 4-6 named hex values
+- **Type:** 2+ rol için typeface (display + body + utility)
+- **Layout:** one-sentence prose description + ASCII wireframe
+- **Signature:** tek unutulmaz element
+
+### Pass 2: Critique
+
+Plan'ı brief ile karşılaştır. "Bu herhangi bir projede yaparım" gibi geliyorsa → revize.
+
+### Pass 3: Build
+
+Sadece plan unique olduktan sonra code yaz. Her renk/type kararı plan'dan türemeli.
+
+### CSS Dikkat
+
+Type-based ve element-based selector'lar birbirini override edebilir. Specificity'ye dikkat.
+
+## Yazım (Copy)
+
+- **End-user bakış açısıyla yaz.** Sistem nasıl inşa edildi değil, kullanıcı ne kontrol ediyor → o.
+- **Active voice.** "Save changes" değil "Submit".
+- **Tutarlı isimlendirme.** Publish butonu → Published toast.
+- **Hatalar yön gösterir.** Özür dilemesin, ne olduğunu söyle.
+- **Boş ekran = davet.** "Henüz yok" değil, ne yapılacağını söyle.
+- **Boş sohbet değil.** Plain verbs, sentence case, no filler.
+
+## Restraint
+
+Bir yerde cesur ol. Signature element tek unutulmaz şey olsun, gerisi sade kalsın. Chanel: "Eve çıkmadan önce aynaya bak ve bir aksesuarı çıkar."
+
+Screenshots ile self-critique yap. Görsel inceleme 1000 token'a bedel.
+
+## Özet
+
+- Subject-first düşün
+- Template default'larından kaçın
+- Tek bir signature element
+- Type, renk, spacing bilinçli
+- Copy = design material, decoration değil
+- Critique twice, build once
+- Restraint > excess
+
+## Reference
+
+- Anthropic orijinal skill: https://github.com/anthropics/skills/tree/main/skills/frontend-design

package/skills/mcp-builder/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: mcp-builder
+description: MCP (Model Context Protocol) server geliştirme rehberi. AI agent'lar için araç expose etmek istediğinde bu skill'i yükle.
+metadata: {"natureco": {"requires": {"bins": ["npx", "node"]}, "os": ["darwin","linux"]}}
+---
+
+# MCP Builder Skill
+
+AI agent'ların tool, resource ve prompt olarak kullanabileceği MCP server'ları geliştirmek için rehber.
+
+## MCP Nedir
+
+Anthropic'in açık protokolü. AI modeller ile veri kaynakları/araçlar arasında standart bağlantı. JSON-RPC tabanlı, server-client mimarisi.
+
+## Ne Zaman Kullan
+
+- NatureCo CLI'yi bir AI agent'a tool olarak bağlamak
+- Yeni bir MCP server sıfırdan yazmak
+- Mevcut bir API/CLI aracını MCP'ye çevirmek
+- stdio vs HTTP+SSE vs streamable-HTTP transport seçmek
+- fastmcp (Python) vs mcporter (Node) arasında seçim yapmak
+
+## Hızlı Başlangıç (Python - fastmcp)
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("natureco-tools")
+
+@mcp.tool()
+def scan_repo(path: str, max_files: int = 200) -> dict:
+    """NatureCo CLI üzerinden repo tarar."""
+    import subprocess
+    result = subprocess.run(
+        ["natureco", "scan", path, "--max", str(max_files)],
+        capture_output=True, text=True, check=True,
+    )
+    return {"output": result.stdout}
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Hızlı Başlangıç (Node - mcporter)
+
+```typescript
+import { McpServer } from "mcporter";
+
+const server = new McpServer({ name: "natureco-tools", version: "1.0.0" });
+
+server.tool("scan_repo", {
+  description: "NatureCo CLI üzerinden repo tarar",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      max_files: { type: "integer", default: 200 },
+    },
+    required: ["path"],
+  },
+}, async ({ path, max_files }) => {
+  return { content: [{ type: "text", text: `Scanned ${path}` }] };
+});
+
+await server.listen({ port: 3000 });
+```
+
+## NatureCo için En İyi Pratikler
+
+- **subprocess.run**: NatureCo CLI'yi subprocess olarak çağır
+- **Type hints**: tüm tool parametrelerine açık tip ver
+- **Docstring**: her tool'un ilk satırı açıklama olmalı
+- **Async tools**: I/O işlemleri için async tanımla
+- **Error handling**: subprocess.CalledProcessError'ı yakala
+
+## Debug
+
+```bash
+# MCP Inspector ile test
+npx @modelcontextprotocol/inspector python my_server.py
+
+# stdIO sunucu stdout'a yazma (protokol bozulur)
+# Tüm logları stderr'e yönlendir
+```
+
+## Production Kontrol Listesi
+
+- Her tool için timeout koy
+- Rate limiting uygula
+- Pagination ekle (büyük listeler için)
+- OAuth 2.1 ile auth ekle (remote sunucular için)
+- Her tool call'unu logla
+
+## Reference
+
+- Spec: https://modelcontextprotocol.io
+- Python SDK: https://github.com/jlowin/fastmcp
+- Node SDK: https://github.com/mcporter-ai/mcporter

package/skills/playwright/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: playwright
+description: Microsoft Playwright MCP ile browser otomasyonu. Sayfa açma, tıklama, form doldurma, ekran görüntüsü alma, accessibility snapshot ve JavaScript çalıştırma.
+metadata: {"natureco": {"requires": {"bins": ["npx", "node"]}, "os": ["darwin","linux","win32"]}}
+---
+
+# Playwright Skill (Browser Otomasyonu)
+
+Microsoft'un `@playwright/mcp` server'ı ile gerçek browser'da (Chromium/Firefox/WebKit) işlem yap.
+
+## Ne Zaman Kullan
+
+- Web sayfası açıp DOM'u incelemek (sadece HTML değil, gerçek JS çalıştırma)
+- Buton tıklamak, form doldurmak, hover/drag/scroll
+- Ekran görüntüsü almak
+- Accessibility snapshot için (model pixel yerine yapı görsün)
+- Sayfada JavaScript çalıştırmak (veri çekmek veya davranış test etmek)
+- Multi-step akış (login, search, checkout) test etmek
+- UI end-to-end doğrulaması
+
+**Kullanma:** basit HTML scraping için `curl` + `web_extract` yeterli.
+
+## Kurulum
+
+```bash
+# Claude Code'a MCP server olarak ekle
+claude mcp add playwright npx @playwright/mcp@latest
+
+# Proje-scoped
+claude mcp add playwright -s project npx @playwright/mcp@latest
+```
+
+İlk çalıştırmada npx `@playwright/mcp` ve Playwright browser bundle (~150 MB) indirilir.
+
+## Tool'lar (En Sık Kullanılanlar)
+
+### Navigasyon
+- `browser_navigate(url)` — URL aç
+- `browser_navigate_back()` / `browser_navigate_forward()`
+- `browser_close()`
+
+### Gözlem
+- `browser_snapshot()` — **en kullanışlı tool**. Accessibility tree + element ref'leri (`[ref=42]`)
+- `browser_take_screenshot(filename?, fullPage?, type?)` — PNG/JPEG screenshot
+- `browser_console_messages(onlyErrors?)` — console.log çıktısı
+- `browser_evaluate(function)` — sayfada JS çalıştır
+
+### Etkileşim
+- `browser_click(element, ref)`
+- `browser_type(element, ref, text, slowly?)`
+- `browser_hover(element, ref)`
+- `browser_drag(fromElement, fromRef, toElement, toRef)`
+- `browser_select_option(element, ref, values)`
+- `browser_press_key(key)` — Enter, Escape, Tab, ArrowDown
+- `browser_scroll(direction, amount?)` — up/down/left/right
+
+### Bekleme
+- `browser_wait_for(time?, text?, textGone?)`
+
+### Tablar
+- `browser_tabs(action, index?)` — list/new/select/close
+
+## Önerilen Workflow
+
+1. `browser_navigate(url)` → `browser_snapshot()` (tersi değil!)
+2. Major DOM değişiklikten sonra **mutlaka** yeni snapshot
+3. **Snapshot tercih et**, screenshot sadece visual review için
+4. Veri çekmek için `browser_evaluate` daha hızlı
+5. İş bitince `browser_close()`
+
+## Login Pattern
+
+```
+1. browser_navigate("https://example.com/login")
+2. browser_snapshot()
+3. browser_type("Email", "[ref=12]", "user@example.com")
+4. browser_type("Password", "[ref=14]", "...")
+5. browser_click("Sign in", "[ref=18]")
+6. browser_snapshot()  # giriş doğrula
+```
+
+## Konfigürasyon
+
+```bash
+claude mcp add playwright npx @playwright/mcp@latest -e HEADLESS=false  # görünür browser
+claude mcp add playwright npx @playwright/mcp@latest -e BROWSER=firefox
+claude mcp add playwright npx @playwright/mcp@latest -e ISOLATED=true    # temiz profil
+```
+
+Env değişkenleri:
+- `HEADLESS` — true (default) veya false
+- `BROWSER` — chromium, firefox, webkit, msedge
+- `ISOLATED` — true = ephemeral profile
+- `VIEWPORT_SIZE` — default 1280x720
+- `USER_DATA_DIR` — persistent profil yolu
+- `CAPTURE_MODE` — screenshot/snapshot/none
+
+## Sınırlamalar
+
+- Dosya download dialog'ları native değil → JS ile tetikle
+- Bazı siteler automation'ı algılar → stealth plugin veya USER_DATA_DIR kullan
+- ~300 MB per browser context
+- Cold start 5-10sn
+- WebSocket/SSE sayfalar flaky olabilir → generous timeout
+
+## Debug
+
+- `browser_console_messages()` — genelde click'in neden başarısız olduğunu gösterir
+- Click işe yaramadıysa → fresh snapshot al (ref değişmiş olabilir)
+- CAPTCHA/login gibi durumlar için `ISOLATED=false` ve gerçek USER_DATA_DIR
+
+## Reference
+
+- Server: https://github.com/microsoft/playwright-mcp
+- Playwright: https://playwright.dev/docs/intro
+- MCP Spec: https://modelcontextprotocol.io