tillerhand 3.43.0 → 3.47.0

package/README.tr.md

@@ -0,0 +1,292 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="kit/assets/banner-dark.svg">
+    <img src="kit/assets/banner-light.svg" alt="TillerHand: Kodu AI yazar, dümen sende." width="100%">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="kit/CHANGELOG.md"><img alt="Sürüm" src="https://img.shields.io/badge/s%C3%BCr%C3%BCm-3.47.0-2a78d6?style=flat-square"></a>
+  <a href="LICENSE"><img alt="Lisans: MIT" src="https://img.shields.io/badge/lisans-MIT-2a78d6?style=flat-square"></a>
+  <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-haz%C4%B1r-d97757?style=flat-square">
+  <img alt="Codex ve Antigravity" src="https://img.shields.io/badge/ayr%C4%B1ca-Codex%20%C2%B7%20Antigravity-5b6577?style=flat-square">
+  <img alt="Node.js 18+" src="https://img.shields.io/badge/Node.js-18%2B-3c873a?style=flat-square">
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · <b>Türkçe</b> · <a href="https://burakdogrul.github.io/TillerHand/kit/guide.tr.html"><b>Rehberi oku →</b></a>
+</p>
+
+<p align="center">
+  <a href="#hiç-bilmiyorsan-adım-adım">Adım adım</a> ·
+  <a href="#hızlı-başlangıç">Hızlı başlangıç</a> ·
+  <a href="#var-olan-proje-adopt">/adopt</a> ·
+  <a href="#nasıl-çalışır">Nasıl çalışır</a> ·
+  <a href="#uzman-kurulu">Kurul</a> ·
+  <a href="#koruma-katmanları">Korumalar</a> ·
+  <a href="#komutlar">Komutlar</a> ·
+  <a href="#lisans">Lisans</a>
+</p>
+
+---
+
+**TillerHand**, [Claude Code](https://claude.com/claude-code) ile bir ürünü fikirden canlıya ve bakıma kadar götüren bir başlangıç kitidir. Kodu AI yazar, **kararları sen verirsin**: her önemli adımda seçenekleri, hangisinin ne zaman daha iyi olduğunu ve önerisini sunar. Bir **uzman kurulu** işi denetler, **koruma katmanları** tehlikeli işlemleri daha olmadan durdurur, proje her an **düzenli bir klasör yapısında** kalır.
+
+> **Önce dil.** `/start` ve `/adopt` tek bir soruyla açılır: AI seninle hangi dilde konuşsun? Türkçe, İngilizce ya da başka bir dil. Bundan sonra sorular, cevaplar, raporlar, pano ve durum çubuğu o dilde gelir; `/language` ile sonradan değişir. Kitin içindeki her şey (komutlar, kurallar, ajanlar, hook'lar, belge şablonları) İngilizce yazılıdır; yalnızca isteğe bağlı Türkiye eki Türkçe kalır.
+
+| | |
+|---|---|
+| **Soru odaklı** | Ürün, teknik, tasarım, veri, güvenlik ve maliyet kararları gerekçeli seçeneklerle sorulur. Tasarım soruları görsel önizlemeyle gelir. |
+| **Senin dilinde** | `/start` ve `/adopt` önce hangi dilde konuşulacağını sorar: Türkçe, İngilizce ya da başka bir dil. Sorular, cevaplar, belgeler, pano ve durum çubuğu o dilde olur; `/language` ile değişir. |
+| **Uzman kurulu** | Ürün, Mimar, Güvenlik, UX, KVKK, QA ve diğer üyeler planı, görevi, commit'i ve fazı denetler. |
+| **Testi ayrı ajan yazar** | Kabul ve saldırgan testlerini kodu yazan değil, ayrı bir ajan koddan önce yazar ve önce kırmızı olur. Kodu yazan test dosyasına dokunamaz; dolaylı yoldan değişen test commit'e giremez. "Bitti" demeden çalıştığı gösterilir. |
+| **Spec ve sapma kontrolü** | Büyük işte ve her hatada mevcut, beklenen ve değişmemesi gereken davranış yazılır; değişmemesi gerekenin testi yoksa kapı kırmızıdır. |
+| **Bulgu raporları** | Teknik, iş, güvenlik, UX, performans ve hukuk için en önemli 20 bulgu; puanlı, düzeltme yöntemiyle. |
+| **Koruma katmanları** | Sır, yıkıcı komut, onaysız prod deploy, zayıflatılan test ve harita dışı dosya daha olmadan durdurulur. |
+| **Canlı önizleme** | Arayüz görevinde dev sunucu açılır, masaüstü ve mobil ekran görüntüsü alınır; `/qa` kabul kriterlerini gerçek tarayıcıda dener. |
+| **Canlıya ve sonrasına** | `/release first` hosting, alan adı, yedek ve geri almayı sağlayıcı sağlayıcı kurdurur. Web ve backend projelerinde canlı site 3 saatte bir duman testiyle izlenir. |
+| **Türkiye eki** | İsteğe bağlı. iyzico ve PayTR bildirimlerinin imza doğrulaması saldırgan testiyle gelir; KVKK yurt dışı aktarım, e-Fatura/e-Arşiv ve Türkçe İ/ı maddeleri birincil kaynağa bağlıdır. |
+| **Kontrol paneli** | `dashboard.html`: durum, dikkat gerektirenler, kararlar, kurul, bulgular, kalite, operasyon, limit; komutlar tek tıkla kopyalanır. |
+| **Limit farkındalığı** | 5 saatlik ve haftalık limit okunur, iş buna göre planlanır. Uyarı verir, işi durdurmaz. |
+| **Doğru kaynak** | Değişebilen bilgi (sürüm, fiyat, mevzuat) birincil kaynaktan, kaynak ve tarihle doğrulanır. |
+| **Geri alma** | `/rollback` son çalışan hale döner; geçmiş silinmez, yarım iş saklanır. |
+| **Anlatıcı mod** | İstersen her değişikliği yazılım bilmeyen birine anlatır gibi sade bir dille açıklar. |
+| **Seni tanır** | Nasıl çalışmak istediğini (konuşma, soru, rapor, kod tarzı) öğrenir. Onayladığın tercihler tüm projelerinde geçerli olur ve bilgisayarında kalır. |
+| **Rol bazlı model** | Planlama, kod, test, inceleme ve doküman için modeli ve effort'u her görevin başında sen seçersin. Test rolüne koddan farklı bir model önerilir: aynı model aynı kör noktayı paylaşır. |
+| **Hatadan öğrenir** | Aynı türden hata tekrar edince onu önleyecek tek bir kural önerir; sen onaylarsan eklenir. |
+
+## Hiç bilmiyorsan: adım adım
+
+Kod yazmayı bilmen gerekmez. Git, terminal ve kurulum işlerini Claude yapar; sen ne istediğini anlatır ve seçim yaparsın.
+
+**1. Hazırlık (bir kez)**
+- Hesaplar: [GitHub](https://github.com) (ücretsiz) ve Claude **Pro** veya **Max** aboneliği.
+- Programlar: [Claude masaüstü uygulaması](https://claude.com/download), [Node.js](https://nodejs.org) (LTS), [Git](https://git-scm.com/downloads).
+
+**2. Projeni oluştur**
+1. Projen için bir klasör aç ve Claude masaüstü uygulamasında **Code** sekmesinde seç.
+2. Kiti kur. İki yoldan birini seç:
+   - Claude'a yaz: `bu klasörde npx tillerhand init komutunu çalıştır`.
+   - TillerHand plugin'ini [bir kez kurduysan](#hızlı-başlangıç) Claude'a `/tillerhand:init` yaz.
+3. Aynı klasörde **yeni oturum aç**. Kitin komutları ve korumaları yeni oturumda yüklenir.
+
+**3. Başlat**
+
+```
+/start Serbest çalışanlar için fatura ve tahsilat takip uygulaması
+```
+
+İlk soru dildir: Türkçe, İngilizce ya da başka bir dil. Claude bundan sonra seninle o dilde konuşur ve sırayla soru sorar. **Her sorunun ilk seçeneği önerilendir**; emin değilsen onu seç. Var olan bir projen varsa `/start` yerine `/adopt` yaz: Claude kodu tarar, belgeleri koddan çıkarır ve projeyi adım adım kitin düzenine getirir.
+
+**4. Her gün**
+
+| Ne zaman | Ne yazarsın |
+|---|---|
+| Çalışmaya başlarken | `/build` (sıradaki görevi kendisi alır, test eder) |
+| Durumu merak edersen | `ne durumdayız?` veya `/dashboard` |
+| Bir şey bozulursa | `/rollback` |
+| Bırakırken | `/wrap-up`, sonra `/clear` |
+
+**Bilmen gerekenler**
+- **Limit:** Pro'da 5 saatlik ve haftalık limit var. Claude %90, %95 ve %99'da uyarır; limit dolarsa yenilenince `/build` ile kaldığın yerden devam edersin.
+- **Onay:** Veritabanı, tasarım, maliyet kararları sorulmadan verilmez. Veri silme, ödeme ve canlıya alma her zaman onay ister.
+- **Devir:** Projeyi başkasına bırakacaksan `/handoff`; devralan `/handoff devral` ile aynı yerden devam eder.
+
+## Hızlı başlangıç
+
+**Gereksinimler:** [Claude Code](https://claude.com/claude-code), Git, Node.js 18+
+
+Üç kurulum yolu var. Üçü de kiti projeye aynı şekilde kurar; birini seç.
+
+**1. npm (önerilen):** terminalde en kısa yol.
+
+```bash
+mkdir yeni-proje && cd yeni-proje
+npx tillerhand init
+claude
+```
+
+**2. Claude Code plugin:** bilgisayara bir kez kurulur, sonra her yeni projede tek komut. Plugin yalnız kurulumu yapar; kit yine projeye dosya olarak kopyalanır ve her seferinde son sürüm gelir.
+
+Bir kez, Claude Code'da (masaüstü uygulamasında `/plugin` açılmazsa terminalde `claude plugin marketplace add …` ve `claude plugin install …` olarak):
+
+```text
+/plugin marketplace add burakdogrul/TillerHand
+/plugin install tillerhand@tillerhand
+```
+
+Her yeni projede, proje klasöründe açılan oturumda:
+
+```text
+/tillerhand:init
+```
+
+**3. git:** kitin kaynağını görmek, değiştirmek ya da katkı vermek için. Kit proje içinde `vibe-kit/` klasöründe durur ve `.gitignore`'a girer.
+
+```bash
+git clone https://github.com/burakdogrul/TillerHand.git vibe-kit
+node vibe-kit/kit/kit.mjs init
+```
+
+- Açılışta Claude Code, kitin skill eklentilerini kurmayı önerir; kabul et.
+- Kit başka bir klasördeyse: `node <kit>/kit/kit.mjs init --project <proje>`.
+- Codex veya Antigravity için: `npx tillerhand init --tool codex` (birden fazlası: `--tool claude,codex`).
+- Önerilen: kod haritası ([codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)). AI kodu dosya dosya okumak yerine sorgular, token tasarrufu sağlar. `/start` kurmayı sorar.
+
+## Var olan proje: /adopt
+
+Kodun zaten varsa kurulum aynı, başlangıç komutu farklı. Projenin kökünde `npx tillerhand init` çalıştır (dosyaların ezilmez; çakışan kit dosyası `.kit-new` olarak yanına konur), yeni oturum aç ve `/adopt` yaz.
+
+1. **Tarar:** stack, klasör yapısı, testlerin durumu ve git geçmişi çıkarılır. Bu oturumda koda dokunulmaz.
+2. **Belgeleri koddan çıkarır:** PRD, stack ve mimari taslak olarak yazılır; neyi beğenmediğin sorulur, eski `CLAUDE.md` kuralları tek tek sorulup `AGENTS.md`'ye taşınır.
+3. **Kritik akışlara test:** giriş, ödeme gibi akışların doğru davranışı sana sorulur; test kodun bugünkü haline değil, senin cevabına göre yazılır.
+4. **Uyum yol haritası:** güvenli zemin, yapıyı ayrı dalda özellik özellik taşıma, bulgular. Sonra her gün `/build`.
+
+## Nasıl çalışır
+
+```mermaid
+flowchart LR
+    A["/start<br/>fikir → plan"] --> B["Faz 0<br/>kurulum, CI, ilk deploy"]
+    B --> C{"Her görev"}
+    C --> D["/plan-task<br/>kararlar + kurul"]
+    D --> E["/build<br/>önce kabul testleri"]
+    E --> F["/review-changes<br/>+ commit kapısı"]
+    F --> G["/wrap-up"]
+    G --> C
+    C -->|"faz sonu"| H["/findings-*<br/>/board convene<br/>/retro"]
+    H --> I["/release first"]
+    I --> J["/maintain"]
+```
+
+**`/start` sihirbazı** fikri dokuz adımda plana çevirir:
+
+| Adım | Ne olur |
+|---|---|
+| 0 Hazırlık | Profil, planlama derinliği, pano, limit |
+| 1 Fikir | Fikir sorgulanır, PRD yazılır |
+| 2 Tip | Web/SaaS, mobil veya backend; AI özelliği var mı |
+| 3 Kurulum | Seçilen tip ve klasör haritası yerleşir |
+| 4 Teknoloji | Tipin karar kataloğu: veritabanı, kimlik, barındırma… |
+| 5 Mimari | Veri modeli, roller, servisler, birim ekonomisi |
+| 6 Kurul | Uzman kurulu kurulur (önce maliyeti söylenir) |
+| 7 Tasarım | Görsel önizlemelerle stil, renk, yazı tipi |
+| 8 Yol haritası | Kabul testi önce gelen, öncelikli görevler |
+| 9 Kapanış | Özet ve ilk görev |
+
+**Karar protokolü:** Her karar noktasında 2-4 seçenek gelir; önerilen ilk sıradadır ve her seçeneğin ne zaman daha iyi olduğu ve bedeli yazar. Geri dönüşü zor kararlarda (veritabanı, auth, ödeme, veri modeli) önce kurulun görüşü alınır. Kararlar `docs/decisions/log.md`'ye yazılır ve bir daha sorulmaz.
+
+## Uzman kurulu
+
+Ürün tipine göre projene özel kurul ajanları oluşturulur. Kurul danışmandır; kritik bulgu (RET) varsa iş bitmez, sana sorulur.
+
+| Tip | Önerilen kurul |
+|---|---|
+| Web / SaaS | Ürün · Mimar · Güvenlik · UX · Performans · KVKK · QA |
+| Mobil | Ürün · Mimar · Güvenlik · UX · Mobil Platform · KVKK · QA |
+| Backend | Ürün · Mimar · Güvenlik · API · DevOps · QA |
+
+| Toplantı | Ne zaman |
+|---|---|
+| Plan | `/plan-task` sonunda |
+| Görev sonu | `/build` sonunda |
+| Commit | Her commit'te (hafif, sadece değişiklik) |
+| Faz sonu, canlıya alma | `/board convene`, `/release first` |
+
+Önemli kararlarda **konsey** çalışır: farklı modeller aynı soruyu birbirinden habersiz cevaplar, birbirini anonim sıralar, başkan sonucu yazar. Sayımı kod yapar; son karar yine senindir.
+
+## Bulgu raporları
+
+Projeyi bir uzman gözüyle tarar, en önemli **20 bulguyu** kanıt, puan (0-100) ve düzeltme yöntemiyle `docs/findings/` altına yazar. Her rapor bir öncekiyle karşılaştırılır ve panoda eğilim olarak görünür.
+
+| Komut | Bakış açısı | Örnek bulgu |
+|---|---|---|
+| `/findings-tech` | Kıdemli mimar | N+1 sorgu, tekrar eden yetki kontrolü |
+| `/findings-business` | Sektörün uzmanı | Eksik iade kuralı, rakiplerin standart özelliği |
+| `/findings-security` | Saldırgan | IDOR, istemciye sızan anahtar |
+| `/findings-ux` | UX araştırmacısı | Boş durum yok, yetersiz kontrast |
+| `/findings-perf` | Performans ve FinOps | Büyük paket, sınırsız AI maliyeti |
+| `/findings-legal` | Uyum uzmanı | Eksik rıza, envanterde olmayan kişisel veri |
+| `/findings-all` | Hepsi, paralel | Birleşik özet ve ortak düzeltme planı |
+
+## Proje yapısı
+
+Her proje bu düzende başlar ve bu düzende kalır. Kod özellik bazlıdır: bir özelliğe ait her şey `features/<özellik>/` altında durur.
+
+```
+.
+├── .claude/          # komutlar, ajanlar, hook'lar, kurul, klasör haritası
+├── .github/          # CI, Dependabot
+├── docs/
+│   ├── product/      # PRD, yol haritası, sözlük, lansman
+│   ├── architecture/ # genel bakış, stack, yapı
+│   ├── decisions/    # karar günlüğü ve ADR'ler
+│   ├── quality/      # test planı, metrikler, retro
+│   ├── security/     # güvenlik kontrol listesi
+│   ├── operations/   # canlıya alma, dağıtım, bakım, hesaplar
+│   └── findings/     # bulgu raporları
+├── src/ veya app/    # özellik bazlı kod
+├── tests/
+└── AGENTS.md · CLAUDE.md · README.md · CHANGELOG.md
+```
+
+Harita dışı yeni dosya sorulur, `*.bak` ve `*-old.*` gibi dağınıklık dosyaları engellenir; CI her PR'da yapıyı denetler.
+
+## Koruma katmanları
+
+| Katman | Ne yapar |
+|---|---|
+| Sır engeli | Koda veya dokümana yazılan API anahtarını engeller |
+| Yıkıcı komut kalkanı | `DROP`, koşulsuz `DELETE`, `db reset` engellenir; prod deploy ve geri alma sorulur |
+| Paket kapısı | Var olmayan paketi engeller (kurulumda ve `npx`, `uvx` ile çalıştırmada); çok yeni veya popüler bir pakete benzeyeni sorar |
+| Yapı koruyucu | Harita dışı dosyayı sorar, dağınıklık dosyalarını engeller |
+| Test ayrımı | Test dosyasına yalnız `test-writer` ajanı yazar; ana oturum ve kod ajanı denerse engellenir |
+| Test koruması | Silinen, atlanan veya gevşetilen testi sorar |
+| Deterministik kapı | Lint, tip, test ve Semgrep çalışmadan commit açılmaz; koda yazılmış makineye özel yolu yakalar |
+| Commit kapısı | Kurul denetimi ve yeşil kapı olmadan commit atılmaz; patch veya betikle değişen test dosyası da durur |
+| Düzenleme kilidi | `/freeze <klasör>` açıkken AI sadece o klasöre yazar |
+| Kapsam kalkanı | Onaylı planın dışındaki dosyaya yazım sorulur |
+| Yapılandırma onayı | Kural ve koruma dosyaları onayın olmadan değişmez |
+| Dev/prod ayrımı | AI ve yerel ortam sadece dev veritabanına bağlanır |
+
+## Komutlar
+
+| Komut | Ne yapar |
+|---|---|
+| `/start [fikir]` | Dokuz adımlı başlangıç sihirbazı |
+| `/adopt` | Var olan projeyi kite alır, uyum yol haritası çıkarır |
+| `/plan-task [görev]` | Kararları sorar, kurul görüşüyle plan çıkarır |
+| `/build [görev]` | Önce kabul testleri, sonra kod, kanıt ve kurul denetimi |
+| `/design` | Görsel önizlemeli tasarım kararları |
+| `/review-changes` | Bağımsız inceleme ve güvenlik ajanları |
+| `/fix-bug [belirti]` | Kök neden, kırmızı test, düzeltme |
+| `/qa` | Arayüz kriterlerini gerçek tarayıcıda test eder |
+| `/findings-<tür>` | Bulgu raporları |
+| `/board` | Kurulu kurar, toplar; `council <soru>` ile konsey |
+| `/dashboard` | Kontrol paneli |
+| `/rollback` | Son çalışan hale döner |
+| `/freeze <klasör>` | Düzenlemeyi tek klasöre kilitler |
+| `/wrap-up` | Oturumu kapatır, ilerlemeyi kaydeder |
+| `/release [first]` | Canlıya alma kontrolleri; `first` hosting, alan adı, yedek ve geri almayı adım adım kurdurur |
+| `/maintain` | Haftalık, aylık, çeyreklik bakım |
+| `/retro` | Dersleri projeye ve kite geri yazar |
+| `/handoff` | Projeyi başkasına devreder veya devralır |
+| `/kit-update` | Projeyi kitin son sürümüne günceller |
+| `/language` | Konuşma dilini değiştirir |
+
+Tüm komutlar, ayarlar, araçlar ve skill'ler **[rehberde](https://burakdogrul.github.io/TillerHand/kit/guide.tr.html)**.
+
+## Codex ve Antigravity
+
+Kit Claude Code için yazıldı; kurallar, komutlar ve korumalar OpenAI Codex ve Google Antigravity'de de çalışır. Kurul tek modelle yürür; soru arayüzü, durum çubuğu ve commit kapısı bu araçlarda yok. Bu araçlar ajan kimliği bildirmediği için test ayrımı orada kural metninde kalır. Kurulum: `node <kit>/kit/kit.mjs init --tool codex` (veya `antigravity`).
+
+## Ölçüm
+
+Aynı görevler kitli ve kitsiz `claude -p` ile koşuldu, gizli testlerle puanlandı (3.18.2, Sonnet, 6 görev, koşul başına 24 koşu):
+
+- İki koşul da gizli testlerin hepsini geçti.
+- Kitin yazdığı testler, koda bilerek eklenen hataların **%63**'ünü yakaladı; kitsiz koşunun testleri **%31**'ini.
+- Kit her koşuda testi koddan önce yazdı; kitsiz koşu hiçbirinde yazmadı.
+
+## Lisans
+
+[MIT](LICENSE) © 2026 Burak Doğrul

package/docs/architecture/overview.md

@@ -1,66 +1,66 @@
-# Mimari
+# Architecture
 
-> Aşama: **0 - Fikir** sonunda yazılır, **2 - Geliştirme** boyunca güncellenir.
-> Yapı değiştikçe bu dosya da değişir. Güncel değilse AI yanlış varsayım yapar.
+> Stage: written at the end of **0 - Idea**, updated throughout **2 - Development**.
+> When the structure changes, this file changes too. If it is out of date, the AI makes wrong assumptions.
 
-## 1. Genel bakış
+## 1. Overview
 
 ```
-[İstemci] ──HTTPS──> [Uygulama/API] ──> [Veritabanı]
+[Client] ──HTTPS──> [App/API] ──> [Database]
                           │
-                          ├──> [Auth sağlayıcı]
-                          ├──> [Ödeme]
+                          ├──> [Auth provider]
+                          ├──> [Payment]
                           └──> [E-posta / AI API / Depolama]
 ```
 
-## 2. Teknoloji seçimi
+## 2. Technology choice
 
-| Katman | Seçim | Neden | Alternatif |
+| Layer | Choice | Why | Alternative |
 |---|---|---|---|
-| Dil | | | |
+| Language | | | |
 | Framework | | | |
-| Veritabanı | | | |
+| Database | | | |
 | Auth | | | |
 | Hosting | | | |
-| Hata takibi | | | |
+| Error tracking | | | |
 
-Ayrıntılı kurallar: `docs/architecture/stack.md`.
+Detailed rules: `docs/architecture/stack.md`.
 
-## 3. Klasör yapısı
+## 3. Folder structure
 
 ```
-[Proje kök klasör ağacı, sadece ana klasörler + her birinin görevi]
+[Project root folder tree, main folders only + the job of each]
 ```
 
-## 4. Veri modeli
+## 4. Data model
 
-| Tablo | Alanlar (önemli olanlar) | İlişkiler | Kişisel veri? | Erişim kuralı |
+| Table | Fields (the important ones) | Relations | Personal data? | Access rule |
 |---|---|---|---|---|
-| users | id, email, created_at | | Evet | Sadece kendisi |
+| users | id, email, created_at | | Yes | Only the user |
 | | | | | |
 
-## 5. Dış servisler
+## 5. External services
 
-| Servis | Amaç | Ortam değişkeni | Ücret / limit | Hesap sahibi |
+| Service | Purpose | Environment variable | Price / limit | Account owner |
 |---|---|---|---|---|
 | | | | | |
 
-## 6. Kimlik doğrulama ve yetki
+## 6. Authentication and authorization
 
-- **Giriş yöntemleri:** [e-posta+şifre / magic link / Google / Apple]
-- **Roller:** [user, admin]
-- **Yetki nerede kontrol ediliyor:** [sunucu tarafı / DB kuralları (RLS) / ikisi]
+- **Sign-in methods:** [email+password / magic link / Google / Apple]
+- **Roles:** [user, admin]
+- **Where authorization is checked:** [server side / DB rules (RLS) / both]
 
-## 7. Ortamlar
+## 7. Environments
 
-| Ortam | URL | Veritabanı | Deploy nasıl |
+| Environment | URL | Database | How it is deployed |
 |---|---|---|---|
-| Lokal | localhost | lokal/dev projesi | - |
-| Önizleme/Staging | | ayrı | PR açılınca |
-| Prod | | ayrı | `main`'e merge |
+| Local | localhost | local/dev project | - |
+| Preview/Staging | | separate | when a PR is opened |
+| Prod | | separate | merge to `main` |
 
-## 8. Bilinen teknik borç
+## 8. Known technical debt
 
-| Ne | Neden böyle | Ne zaman düzeltilmeli |
+| What | Why it is this way | When it should be fixed |
 |---|---|---|
 | | | |

package/docs/architecture/stack.md

@@ -1,4 +1,4 @@
 # Stack
 
-> Proje tipi henüz seçilmedi. `/start` tipi sorar ve bu dosyayı seçilen tipin
-> teknoloji, kural ve karar noktaları dosyasıyla değiştirir.
+> The project type is not chosen yet. `/start` asks for the type and replaces this file with the
+> technology, rules and decision points file of the chosen type.

package/docs/archive/README.md

@@ -1,9 +1,9 @@
-# Arşiv
+# Archive
 
-Artık geçerli olmayan ama saklanması gereken dokümanlar. Silmek yerine buraya taşı ve dosyanın başına şunu ekle:
+Docs that are no longer valid but must be kept. Instead of deleting, move them here and add this at the top of the file:
 
 ```
-> Arşivlendi: YYYY-AA-GG · Neden: [...] · Yerine geçen: [docs/... veya "yok"]
+> Archived: YYYY-MM-DD · Reason: [...] · Replaced by: [docs/... or "none"]
 ```
 
-Arşivdeki dokümanlar AI için bağlam değildir; güncel kararlar `docs/decisions/` altındadır.
+Docs in the archive are not context for the AI; current decisions are under `docs/decisions/`.

package/docs/decisions/adr-template.md

@@ -1,25 +1,25 @@
-# ADR-NNNN: [Kısa başlık]
+# ADR-NNNN: [Short title]
 
-- **Tarih:** YYYY-AA-GG
-- **Durum:** Önerildi / Kabul edildi / Yerine geçti: ADR-NNNN
-- **Kapı:** tek yönlü / çift yönlü
-- **Karar günlüğü:** #N (`docs/decisions/log.md`)
-- **Kurul görüşü:** [katılan üyeler ve sonuç]
+- **Date:** YYYY-AA-GG
+- **Status:** Proposed / Accepted / Superseded by: ADR-NNNN
+- **Door:** one-way / two-way
+- **Decision log:** #N (`docs/decisions/log.md`)
+- **Board opinion:** [members who took part and the result]
 
-## Bağlam
+## Context
 
-[Hangi problem bu kararı gerektirdi? Kısıtlar neler?]
+[Which problem required this decision? What are the constraints?]
 
-## Seçenekler
+## Options
 
-| Seçenek | Artı | Eksi |
+| Option | Pro | Con |
 |---|---|---|
 | | | |
 
-## Karar
+## Decision
 
-[Ne seçildi ve neden? Kullanıcının seçimi.]
+[What was chosen and why? The user's choice.]
 
-## Sonuçlar
+## Consequences
 
-[Neyi kolaylaştırır, neyi zorlaştırır, neye bağımlı kılar? Geri dönmek gerekirse maliyeti ne?]
+[What does it make easier, what does it make harder, what does it make us depend on? What is the cost of going back?]

package/docs/decisions/log.md

@@ -1,20 +1,20 @@
-# Kararlar
+# Decisions
 
-> İki bölüm var:
-> 1. **Karar günlüğü:** Sorulan her karar tek satır. Kapı: `tek` (geri dönüşü pahalı) / `çift` (kolay geri alınır). Kim verdi: `kullanıcı` veya `otomatik` (soru modu kapalıyken).
-> 2. **ADR'ler** (Architecture Decision Record): Mimariyi veya uzun vadeyi etkileyen kararlar ve bütün tek yönlü kararlar ayrı dosyada: `docs/decisions/adr-NNNN-kisa-ad.md` (şablon: `adr-template.md`).
+> There are two sections:
+> 1. **Decision log ("Karar günlüğü"):** one line for every decision asked. Door: `tek` (one-way, costly to reverse) / `çift` (two-way, easy to reverse). Decided by: `kullanıcı` (user) or `otomatik` (automatic, when question mode is off).
+> 2. **ADRs** (Architecture Decision Record): decisions that affect the architecture or the long term, and all one-way decisions, go in a separate file: `docs/decisions/adr-NNNN-kisa-ad.md` (template: `adr-template.md`).
 >
-> Bir karar sormadan önce buraya bak: daha önce verilmişse tekrar sorma, ona uy.
-> Kararlar silinmez; değişirse yeni satır eklenir ve eskisinin yanına "→ #N ile değişti" yazılır.
+> Look here before asking a decision: if it was made before, do not ask again, follow it.
+> Decisions are never deleted; if one changes, a new line is added and "→ changed by #N" is written next to the old one.
 
 ## Karar günlüğü
 
-`/dashboard` panosu bu tabloyu okur; sütunları değiştirme.
+`/dashboard` reads this table; do not change the columns.
 
-| # | Tarih | Aşama | Konu | Soru | Seçilen | Kapı | Karar veren |
+| # | Date | Stage | Topic | Question | Chosen | Door | Decided by |
 |---|---|---|---|---|---|---|---|
 
-## ADR listesi
+## ADR list
 
-| ADR | Başlık | Durum | Günlük no |
+| ADR | Title | Status | Log no |
 |---|---|---|---|

package/docs/findings/README.md

@@ -1,22 +1,22 @@
-# Bulgular
+# Findings
 
-Projeyi farklı uzman gözleriyle tarayan raporlar. Her rapor en önemli en fazla 20 bulguyu kanıtla, 0-100 önem puanıyla ve düzeltme yöntemiyle sıralar; ayrıca alan için 0-100 sağlık puanı verir. Yöntem: `.claude/findings/protocol.md`.
+Reports that scan the project through different expert eyes. Each report ranks at most the 20 most important findings with evidence, a 0-100 severity score and a fix method; it also gives a 0-100 health score for the area. Method: `.claude/findings/protocol.md`.
 
-| Komut | Bakış açısı | Klasör |
+| Command | Viewpoint | Folder |
 |---|---|---|
-| `/findings-tech` | Kıdemli mimar: hatalar, tekrar ve kullanılmayan kod, yapı, testler | `tech/` |
-| `/findings-business` | Sektör uzmanı: iş akışları, iş kuralları, gelir, rekabet | `business/` |
-| `/findings-security` | Saldırgan: erişim, enjeksiyon, sırlar, bağımlılıklar | `security/` |
-| `/findings-ux` | Kullanıcı ve UX araştırmacısı: akışlar, erişilebilirlik, metin | `ux/` |
-| `/findings-perf` | Performans ve FinOps: yavaş yollar, maliyet | `perf/` |
-| `/findings-legal` | Uyum uzmanı: KVKK, regülasyon, lisans (hukuki görüş değildir) | `legal/` |
-| `/findings-all` | Seçilen türlerin hepsi + birleşik özet | `summary-*.md` |
+| `/findings-tech` | Senior architect: bugs, duplicate and unused code, structure, tests | `tech/` |
+| `/findings-business` | Industry expert: workflows, business rules, revenue, competition | `business/` |
+| `/findings-security` | Attacker: access, injection, secrets, dependencies | `security/` |
+| `/findings-ux` | User and UX researcher: flows, accessibility, copy | `ux/` |
+| `/findings-perf` | Performance and FinOps: slow paths, cost | `perf/` |
+| `/findings-legal` | Compliance expert: KVKK, regulation, license (not legal advice) | `legal/` |
+| `/findings-all` | All of the selected types + a combined summary | `summary-*.md` |
 
-Her türün klasöründe tarihli raporlar ve en son raporun kopyası (`latest.md`) bulunur.
+Each type's folder holds dated reports and a copy of the latest report (`latest.md`).
 
 ## Raporlar
 
-`/dashboard` panosu bu tabloyu okur; sütunları değiştirme. Sağlık ve önceki puan `NN` biçiminde yazılır.
+The `/dashboard` dashboard reads this table; do not change the columns. Write health and the previous score in the `NN` format.
 
-| Tarih | Tür | Sağlık | Önceki | Bulgu | Kritik | Rapor |
+| Date | Type | Health | Previous | Findings | Critical | Report |
 |---|---|---|---|---|---|---|

package/docs/findings/config.md

@@ -1,22 +1,22 @@
-# Bulgu ayarları
+# Findings settings
 
-> `/findings-*` komutları bu dosyayı okur. Boş alanları ilk çalıştırmada AI sorup doldurur.
+> The `/findings-*` commands read this file. The AI asks for the empty fields on the first run and fills them in.
 
 ## Business
 
-**Sektör:** -
-**Alt alan:** -
-**Uzman rolü:** -
-**Pazar:** -
-**Hedef müşteri:** -
-**Rakipler:** -
+**Sector:** -
+**Subfield:** -
+**Expert role:** -
+**Market:** -
+**Target customer:** -
+**Competitors:** -
 
 ## Legal
 
-**İlgili regülasyonlar:** -
-**Kişisel veri türleri:** -
-**Veri işlenen ülkeler:** -
+**Relevant regulations:** -
+**Personal data types:** -
+**Countries where data is processed:** -
 
-## Genel
+## General
 
-**Hariç tutulan yollar:** sandbox/, docs/archive/
+**Excluded paths:** sandbox/, docs/archive/

package/docs/legal/privacy-kvkk.md

@@ -47,7 +47,7 @@ Vercel, Supabase, AWS, OpenAI, Sentry gibi yurt dışı sunuculu servisler = yur
 
 ## 6. Mobil mağaza ek gereksinimleri
 
-`docs/architecture/stack.md` (mobil) → "Canlıya alma" bölümüne bak: App Store gizlilik etiketleri, Google Play Veri Güvenliği formu, uygulama içi hesap silme.
+`docs/architecture/stack.md` (mobil) → "Go live (extra)" bölümüne bak: App Store gizlilik etiketleri, Google Play Veri Güvenliği formu, uygulama içi hesap silme.
 
 ## 7. Gözden geçirme