@analitikisler/ai-tag-debugger 0.16.0 → 0.17.0

package/README.tr.md

@@ -56,7 +56,7 @@ Platformlar: GA4 (sitenin kendi alan adındaki sunucu tarafı GTM uç noktaları
 
 GA4 istekleri başka bir ana makinedeki bir sunucu konteynerine gidiyorsa ya da yükleyicisi oradan sunuluyorsa, rapor bir bilgi bulgusu ekler: konteynerin ad platformlarına ilettiği event'ler tarayıcıdan geçmez, bu yüzden burada görülemez.
 
-`gtm_container` dışa aktarımı verildiğinde, her hatalı event onu gönderen GTM etiketini ve tetiklendiği tetikleyiciyi adlandırır (ya da hiçbir etiketin göndermediğini söyler). Yapay zekâ modeli gerekmez.
+`gtm_container` dışa aktarımı verildiğinde, her hatalı event onu gönderen GTM etiketini ve tetiklendiği tetikleyiciyi adlandırır (ya da hiçbir etiketin göndermediğini söyler). Her etiket ardından tetikleyicisinin o yolculukta tetiklenip tetiklenmediğini, tetiklenmediyse nedenini söyler: etiket duraklatılmış, hiçbir dataLayer gönderimi tetikleyicinin event'ini taşımamış, bir tetikleyici koşulu sağlanmamış (gönderimdeki değerle birlikte; değer, GTM'in Data Layer Variable'larının okuduğu gibi birikimli dataLayer'dan okunur), bir istisna tetikleyicisi engellemiş ya da event tetiklendiğinde etiketin gerektirdiği onay reddedilmiş. Her şey tetiklendiği hâlde istek yine de hatalıysa bunu söyler ve etiketin kendi kurulumunu işaret eder. Tıklama, form, görünürlük ve zamanlayıcı tetikleyicilerini GTM sayfada değerlendirdiği için, bunlar `gtm.click` türü event'leri dataLayer'a ulaşmadıkça değerlendirilemez olarak raporlanır. Bunların tümü yakalanan dataLayer'dan, yapay zekâ modeli olmadan değerlendirilir.
 
 ### Kontrol edilecek platformları seçin
 
@@ -71,7 +71,7 @@ Her denetim ayrıca başlangıç sayfasını her çerez onay seçimi için bir k
 ## Nasıl çalışır
 
 1. **Gezinme:** Yapay zekâ modeli, sade bir dille yazılmış bir hedef ("sepete herhangi bir ürün ekle ve test ödeme yöntemiyle siparişi tamamla") ve sayfanın metin görünümünü alır. İki araçla çalışır: `browser_action` (goto, click, fill, select, scroll, wait) ve `finish`. Playwright ile her seferinde bir adım atar.
-2. **Yakalama:** Bir takip uç noktasına giden her istek normalleştirilmiş isteklere ayrıştırılır ve isteği tetikleyen adımla etiketlenir. Her dataLayer gönderimi, bir başlatma betiği aracılığıyla kaydedilir; `gtag('consent', ...)` komutları da buna dahildir. Varsayılan olarak GA4, Google Ads, Meta, TikTok, Microsoft Ads, LinkedIn, Pinterest, Snapchat ve X'in toplama istekleri yerelde yanıtlanır, bu yüzden **test trafiği bu gerçek hesaplara ulaşmaz**. Diğer satıcıların etiketleri isteklerini göndermeye devam eder; zaman akışının ağ bölümü her çağrıyı ve yerelde yanıtlanıp yanıtlanmadığını gösterir.
+2. **Yakalama:** Bir takip uç noktasına giden her istek normalleştirilmiş isteklere ayrıştırılır ve isteği tetikleyen adımla etiketlenir. Her dataLayer gönderimi, bir başlatma betiği aracılığıyla kaydedilir; `gtag('consent', ...)` komutları da buna dahildir. Varsayılan olarak aracın ayrıştırabildiği her platformun (GA4, Google Ads, Meta, TikTok, X, LinkedIn, Microsoft Ads, Pinterest, Snapchat, Criteo, Klaviyo, Adobe Analytics, Matomo ve Piwik PRO) toplama istekleri ile Google'ın dönüşüm, yeniden pazarlama ve onay ping'leri yerelde yanıtlanır, bu yüzden **test trafiği bu gerçek hesaplara ulaşmaz**. Aracın yalnızca ana makinesinden tanıdığı satıcıların (Clarity ve Hotjar gibi) etiket yüklemeleri ve istekleri dışarı gitmeye devam eder; zaman akışının ağ bölümü her çağrıyı ve yerelde yanıtlanıp yanıtlanmadığını gösterir.
 3. **Kontrol:** Deterministik kurallar, yakalanan istekleri ölçümleme planınızla karşılaştırır. Bu bölüm yapay zekâ çağrısı gerektirmez, bu yüzden sonuçlar tekrarlanabilirdir.
 4. **Açıklama:** Model bulguları, adım başına istekleri ve (isteğe bağlı olarak) GTM konteyner dışa aktarımınızı okur. Her sorun için olası nedeni ve düzeltmeyi yazar, ilgili etiket ve tetikleyicileri adlandırarak.
 
@@ -164,7 +164,7 @@ Genel kurulum, kısa bir takma ad olan `aitd`'yi de ekler: `aitd run --site …
 
 Ya da kurmadan çalıştırın: `npx -y @analitikisler/ai-tag-debugger run --site … --journey add_to_cart`.
 
-Komutları görmek için `aitd --help`, her komutun seçenekleri için `aitd run --help` (ya da `plan`, `replay`, `mcp`) çalıştırın.
+Komutları görmek için `aitd --help`, her komutun seçenekleri için `aitd run --help` (ya da `plan`, `replay`, `mcp`) çalıştırın. Bir şey çalışmıyorsa `aitd doctor`, Node'u, Chromium'u, yapay zekâ anahtarınızı ve veri klasörünü denetler ve neyin düzeltileceğini söyler.
 
 ### Demo mağazayı deneyin (kaynak koddan)
 
@@ -311,13 +311,32 @@ Planlar ve çalıştırmalar, aracı çalıştırdığınız klasördeki `aitd/`
 aitd/
   example.com/                      sitenin ana makinesi, www. olmadan
     plans/2026-10-16_0900/          measurement-plan.json, plan.html, plan.xlsx (dışa aktarımdan sonra)
-    runs/2026-10-16_0912/           report.html, report.md, timeline.csv, capture.json
-                                    ve plan-check.json (--against ile)
+    runs/2026-10-16_0912/           report.html, report.md, timeline.csv, capture.json, steps.json,
+                                    junit.xml, summary.json ve plan-check.json (--against ile)
+    history.json                    kayıtlı her çalıştırmanın küçük bir özeti, eğilim için (aşağıya bakın)
 ```
 
 Bir kimlik, yerel saat `YYYY-MM-DD_HHMM` biçimindedir. O dakika zaten alınmışsa saniye eklenir (`_HHMMSS`). Hiçbir şey değiştirilmez: her taslak, içe aktarma ve çalıştırma yeni bir klasör alır. `aitd/` klasörünü başka bir yerde tutmak için `--data-dir <dir>` kullanın. `replay` ve `--save-site` klasörleri etkilenmez.
 
-Her rapor, çalıştırmayı sitenin `runs/` içindeki bir önceki çalıştırmasıyla karşılaştıran "Son çalıştırmadan bu yana değişenler" bölümüyle açılır, örneğin `2 olay düzeldi, 1 yeni sorun`, ve her birini listeler. İki çalıştırma da `--against` kullandıysa plan kapsamı karşılaştırılır (Eksik iken Uygulanmış olan bir olay düzelmiş sayılır); aksi halde sağlık bulguları karşılaştırılır. Bir sitenin ilk çalıştırmasında karşılaştırılacak bir şey olmadığı yazar. Ayarlanacak bir bayrak yoktur. Karşılaştırma `capture.json` içinde `changes` altında da kaydedilir.
+Her raporda, çalıştırmayı sitenin `runs/` içindeki bir önceki çalıştırmasıyla karşılaştıran bir "Son çalıştırmadan bu yana değişenler" bölümü bulunur, örneğin `2 olay düzeldi, 1 yeni sorun`, ve her birini listeler: neyin düzeldiği (önceki durumuyla birlikte), neyin yeni olduğu ve neyin hâlâ açık olduğu. İki çalıştırma da `--against` kullandıysa plan kapsamı karşılaştırılır (Eksik iken Uygulanmış olan bir olay düzelmiş sayılır); aksi halde sağlık bulguları karşılaştırılır. Bir sitenin ilk çalıştırmasında karşılaştırılacak bir şey olmadığı yazar. Ayarlanacak bir bayrak yoktur. Karşılaştırma `capture.json` içinde `changes` altında da kaydedilir.
+
+### Çalıştırmalar arasında eğilim
+
+İkinci kayıtlı çalıştırmadan itibaren araç, sitenin son 30 çalıştırmasına da birlikte bakar. Sayıların ardından CLI, sonuç satırını ve en fazla üç eğilim satırı yazdırır:
+
+```
+2 bozuk · 1 risk · 1 uyarı · 0 bilgi · 4 sorunsuz
+Sonuç: Kaldı · purchase izlemesi bozuk (mobile) · puan 25/100
+5 çalıştırmada eğilim (2026-10-01 → 2026-10-07): iyileşiyor. Şimdi 0 bozuk · 1 risk · 2 uyarı; 3 çalıştırma önce 2 bozuk · 1 risk · 0 uyarı.
+En uzun süredir açık: Meta PageView before_consent 4 yerde 2026-10-01 tarihinden beri (5 çalıştırma); GA4 add_to_cart duplicate 4 yerde 2026-10-03 tarihinden beri (3 çalıştırma).
+Her seferinde tamamlanmayan yolculuklar: checkout (mobile) 80%.
+```
+
+Aynı satırlar, çalıştırmaların metin biçimindeki bir mini grafiğiyle (sparkline; çalıştırma başına bir karakter, yolculuklarının tümü tamamlanmayan çalıştırma için `·`) `report.md` ve `report.html` içindeki **Eğilim** bölümünü oluşturur. Bir sorun, yolculuğunu tamamlayan son çalıştırma onu hâlâ gösteriyorsa *açık* sayılır; yolculuğu erken duran bir çalıştırma hiçbir şey kanıtlamaz, bu yüzden ne bir şeyi düzeltir ne de geri getirir. *Gelip giden* sorunlar (görüldü, kayboldu, yine görüldü) ayrıca adlandırılır, çünkü bunlar genellikle bir düzeltmeye değil, zamanlamaya ya da yapay zekânın seçtiği ürüne bağlıdır. Yön, tamamlanan son birkaç çalıştırmayı öncekilerle karşılaştırır.
+
+`aitd history --site <url>` eğilimi tek başına yazdırır: her çalıştırma için sayıları ve puanıyla (`3·broken + 2·risk + warning`, düşük olan iyidir) bir satır, mini grafik ve yukarıdaki satırlar. `--limit <n>` yalnızca en yeni `n` çalıştırmayı okur (varsayılan 30), `--lang tr` satırları Türkçeye çevirir ve `--json`, betikler için eğilim serisini, bulgu başına zaman çizelgesini (ilk görülme, son görülme, ne zamandan beri açık, hangi çalıştırmada düzeldi, gelip gidiyor mu) ve yolculuk tamamlanma oranlarını yazdırır.
+
+Özetler `aitd/<alan adı>/history.json` dosyasında durur, çalıştırma başına yaklaşık 2 KB; kayıtlı her çalıştırma `capture.json` dosyasını yazdıktan sonra bu dosyayı günceller. Dosya bir önbellektir: içinde olmayan bir çalıştırma klasörü `capture.json` dosyasından okunur, silinen bir klasör sonraki güncellemede listeden düşer ve dosyayı silmek her zaman güvenlidir. `--out` ile gönderilen çalıştırmalar ve tekrar oynatmalar geçmişin parçası değildir.
 
 ## Ne test edileceğini seçin
 
@@ -359,8 +378,11 @@ Gezinmenin her adımı bir model çağrısıdır; bu yüzden kullanım **yolculu
 - **Büyük sayfaların daha pahalı olmasını bekleyin.** Her adım, sayfa görünümünü (en fazla 250 öğe ve 3.000 karakter metin) modele gönderir; bu yüzden yoğun sayfalar basit sayfalardan adım başına daha fazla token kullanır.
 - **Tekrar çalıştırmalar son yolu baştan kullanır.** Bir yolculuk sitede bir kez tamamlandıktan sonra, bir sonraki çalıştırma yapay zekâya o çalıştırmanın geçtiği sayfaları sırasıyla verir; böylece keşfetmek yerine doğrudan hedefe gider. Yalnızca aynı hedef için kullanılır, yalnızca 0.14.0 ve sonrasıyla kaydedilen çalıştırmalardan alınır ve yalnızca yapay zekâlı çalıştırmalarda kullanılır. `--out` ya da `replay` ile kullanılmaz. Site değiştiyse ve yol artık uymuyorsa yapay zekâ başka bir yol izler.
 - **Raporu odaklı tutmak için `--events` kullanın.** Gezinmeyi kısaltmaz, bu yüzden kullanımı pek değiştirmez.
-- **Yapay zekâsız tekrar oynatın.** Bir yapay zekâlı çalıştırmadan sonra adımları kaydetmek için `--save-steps <dosya>` ekleyin; sonra o ayar dosyasını her dağıtımda `--scripted --no-ai` ile çalıştırın. Bkz. [Adımları kaydedin ve yapay zekâ olmadan tekrar oynatın](#adımları-kaydedin-ve-yapay-zekâ-olmadan-tekrar-oynatın).
+- **Yapay zekâsız tekrar oynatın.** Tamamlanan her çalıştırma attığı adımları çalıştırma klasörüne `steps.json` olarak kaydeder; `--scripted --no-ai`, kendi sabit adımları olmayan bir yolculuk için son tamamlanan çalıştırmanın adımlarını tekrarlar. Bir yolculuğu yapay zekâyla bir kez çalıştırın, sonra her dağıtımda tekrar oynatın. Bkz. [Adımları kaydedin ve yapay zekâ olmadan tekrar oynatın](#adımları-kaydedin-ve-yapay-zekâ-olmadan-tekrar-oynatın).
 - **Bir sohbet uygulaması kullanın.** MCP üzerinden gezinmeyi sohbet uygulamasının kendi modeli yapar, bu yüzden hiç API anahtarı kullanılmaz.
+- **Geçici hatalar bir çalıştırmaya mal olmaz.** Model API'sinden gelen bir hız sınırı, aşırı yük yanıtı ya da kopan bağlantı (429, 529, 5xx ve benzerleri) `retry-after` başlığına uyularak, artan bir bekleme süresiyle en fazla 3 kez yeniden denenir; ağın düşürdüğü ya da zaman aşımına uğrayan bir sayfa yüklemesi de 2 saniye sonra bir kez daha denenir. Hatalı bir anahtar ya da reddedilen bir sayfa gibi diğer hatalar hemen başarısız olur.
+
+Çalışma süresi ayrı bir konudur: `--concurrency 3`, her biri kendi tarayıcısında olmak üzere aynı anda en fazla üç yolculuk çalıştırır; böylece birkaç yolculuk ve görünüm içeren bir çalıştırma çok daha erken biter. Aynı model çağrılarını yapar, yalnızca daha sık aralıklarla; bu yüzden sağlayıcı size hız sınırı uyguluyorsa `1` ya da `2` ile kalın.
 
 ### Yeni bir sürümü kayıtlı sitelere karşı kontrol edin
 
@@ -377,14 +399,34 @@ npx @analitikisler/ai-tag-debugger replay saved/*
 
 ### Adımları kaydedin ve yapay zekâ olmadan tekrar oynatın
 
-`--save-steps <dosya>`, her yolculuğun attığı adımları bir ayar dosyasının `journeys[].steps` alanına yazar. Dosya yoksa oluşturur; ayar dosyasında plan yoksa çalıştırmanın planını da kaydeder. Aynı ayar dosyası yolculuğu, yapay zekâ modeli ve API anahtarı olmadan tekrarlar:
+Tamamlanan her çalıştırma, her yolculuğun attığı adımları çalıştırma klasörüne, `aitd/<alan adı>/runs/<id>/steps.json` dosyasına kaydeder. Bir `--scripted --no-ai` çalıştırması, kendi `steps` alanı olmayan her yolculuk için bu adımları tekrarlar: sitenin o yolculuğu tamamlayan en yeni çalıştırmasını alır (varsa aynı görünümdekini, yoksa diğer görünümdekini) ve hangi çalıştırmayı tekrar oynattığını yolculuğun `▶` satırının altında söyler. Böylece yapay zekâ her yolculuk için bir kez gerekir; sonraki her çalıştırmanın maliyeti sıfırdır:
+
+```bash
+ai-tag-debugger run --site https://www.yourshop.com --journey purchase
+ai-tag-debugger run --site https://www.yourshop.com --journey purchase --scripted --no-ai
+```
+
+Site değiştiğinde ve kayıtlı bir adım artık öğesini bulamadığında yolculuk, o çalıştırmanın adımlarının artık siteye uymadığını söyleyen bir notla tamamlanmamış olarak biter; yolculuğu yapay zekâyla bir kez daha çalıştırın, sonraki tekrar yeni adımları kullanır. Sitede hiç tamamlanmamış bir yolculuk, çalıştırmayı tarayıcı açılmadan durdurur. Yalnızca `aitd/` içine kaydedilen çalıştırmalar tekrar oynatılır: `--out` ile başka bir yere gönderilen ya da MCP üzerinden yapılan bir çalıştırma da `steps.json` yazar, ama sonraki çalıştırma oraya bakmaz. Adımlar atıldıkları gibi, yazılan değerler dahil saklanır (bir forma yazılan e-posta adresi `steps.json` içinde yazıldığı haliyle durur, çünkü tekrar oynatmanın onu yeniden yazması gerekir); bu yüzden yolculuklarda test verisi kullanın ve çalıştırma klasörünü sürüm denetiminin dışında tutun.
+
+Adımları bunun yerine deponuzda tutmak için `--save-steps <dosya>`, bunları bir ayar dosyasının `journeys[].steps` alanına yazar. Dosya yoksa oluşturur; ayar dosyasında plan yoksa çalıştırmanın planını da kaydeder. Aynı ayar dosyası yolculuğu, yapay zekâ modeli ve API anahtarı olmadan tekrarlar:
 
 ```bash
 ai-tag-debugger run --site https://www.yourshop.com --journey purchase --save-steps ai-tag-debugger.config.json
 ai-tag-debugger run --config ai-tag-debugger.config.json --scripted --no-ai
 ```
 
-Bir yolculuk her iki görünümde de çalıştıysa yalnızca ilk görünümün adımları tutulur. Ayar dosyasını depoda tutun ve ikinci komutu her dağıtımda çalıştırarak aynı yolculuğu hiçbir model çağrısı yapmadan kontrol edin.
+Bir yolculuk her iki görünümde de çalıştıysa yalnızca ilk görünümün adımları tutulur. İkinci komutu her dağıtımda çalıştırarak aynı yolculuğu hiçbir model çağrısı yapmadan kontrol edin.
+
+### Bilinen bulguları kabul edin
+
+`--fail-on`, bir düzeydeki her bulguda CI işini başarısız yapar. Bir bulgu biliniyorsa ve yakında düzeltilmeyecekse, örneğin onaydan önce tetiklenen bir satıcı pikseli, bir temel dosya (baseline) sonraki çalıştırmaların yalnızca yeni bulgularda başarısız olmasını sağlar. Mevcut her bulguyu bir dosyaya yazmak için bir kez `--update-baseline` ile çalıştırın, dosyayı gözden geçirin ve depoya ekleyin:
+
+```bash
+ai-tag-debugger run --config ai-tag-debugger.config.json --scripted --no-ai --baseline baseline.json --update-baseline
+ai-tag-debugger run --config ai-tag-debugger.config.json --scripted --no-ai --baseline baseline.json --fail-on warning
+```
+
+Dosyada her bulgu için bir kayıt bulunur: çalıştırmanın eşleştirme yaptığı bir `key` (kontrol, platform, event, yolculuk, görünüm ve eksik parametreler için hangileri olduğu) ve dosyayı okuyan kişi için geri kalanı. Bir bulguda yeniden başarısız olmaya başlamak için kaydını silin, ya da neden kabul edildiğini söyleyen bir `"note"` ekleyin; notlar bir sonraki `--update-baseline` çalıştırmasında korunur. Kabul edilen bir bulgu raporda "Kabul edildi" etiketiyle kalır, sayılara ve yapay zekâ açıklamasına alınmaz ve `--fail-on` için sayılmaz. Sayıların ardından çalıştırma, kaç bulgunun kabul edildiğini ve temel dosyadaki kaç kaydın bayatladığını, yani artık görülmediğini yazdırır; böylece dosya sadeleştirilebilir. Yalnızca bazı görünümlerde ya da yolculuklarda kabul edilen bir sorun kısmen kabul edilmiş olarak bildirilir ve sayılmaya devam eder; başka bir site için yazılmış bir temel dosya ise uyarı verir. Ayar dosyasındaki, ayar dosyasına göre bağıl `"baseline": "baseline.json"`, seçeneği her seferinde vermekten kurtarır; MCP `run_audit` aracı da `baseline` alır.
 
 ## Sitenizi yapılandırın
 
@@ -409,17 +451,19 @@ Bir yolculuk her iki görünümde de çalıştıysa yalnızca ilk görünümün
 |---|---|
 | `site` | Temel URL. Mümkünse staging kullanın. |
 | `plan` | Ölçümleme planı: bir dosya yolu ya da satır içi bir nesne (aşağıya bakın). Hazır yolculuklarla isteğe bağlıdır. `--against` ile çalışan bir çalıştırma bunun yerine o planı kullanır. |
-| `gtm_container` | İsteğe bağlı GTM konteyner dışa aktarımı (Yönetici → Konteyneri dışa aktar). Her hatalı event, onu gönderen etiketi ve tetikleyicisini adlandırır (ya da hiçbir etiketin göndermediğini söyler), yapay zekâ modeli olmadan da. |
+| `gtm_container` | İsteğe bağlı GTM konteyner dışa aktarımı (Yönetici → Konteyneri dışa aktar). Her hatalı event, onu gönderen etiketi ve tetikleyicisini adlandırır (ya da hiçbir etiketin göndermediğini söyler) ve o tetikleyicinin yolculukta tetiklenip tetiklenmediğini, tetiklenmediyse nedenini söyler (duraklatılmış etiket, event'i taşıyan gönderim yok, görülen değerle birlikte sağlanmayan bir koşul, engelleyen bir tetikleyici, reddedilen onay); yakalanan dataLayer'dan, yapay zekâ modeli olmadan değerlendirilir. |
 | `viewports` | `desktop` ve/veya `mobile`. |
+| `concurrency` | Varsayılan `1`. Aynı anda kaç yolculuğun (ve onay senaryosunun) çalışacağı, her biri kendi tarayıcısında, en fazla `8`. `--concurrency` ile aynıdır. |
 | `journeys` | `--journey` ile hazır yolculuk seçtiğinizde, `--goal` ile bir yolculuk tarif ettiğinizde ya da `--against` ile bir plana karşı kontrol ettiğinizde isteğe bağlıdır. |
 | `journeys[].goal` | Yapay zekânın sade bir dille ne yapacağı. |
 | `journeys[].start` | İsteğe bağlı başlangıç yolu (varsayılan `/`). |
-| `journeys[].steps` | `--scripted` çalıştırmaları için isteğe bağlı sabit adımlar: `{ "action": "click", "selector": "#add-to-cart" }`. |
+| `journeys[].steps` | `--scripted` çalıştırmaları için isteğe bağlı sabit adımlar: `{ "action": "click", "selector": "#add-to-cart" }`. Bunlar yoksa `--scripted`, sitenin o yolculuğu son tamamlayan çalıştırmasının adımlarını tekrarlar. |
 | `allowed_hosts` | Yolculukların ziyaret edebileceği başka ana makineler, örneğin barındırılan bir ödeme için `["checkout.payments-provider.com"]`. Tarayıcı aksi halde `site` ana makinesinde ve alt alan adlarında kalır. `--allow-host` ile aynıdır. |
 | `providers` | Kontrol edilecek takip platformları, örneğin `["ga4", "meta"]`. Varsayılan `["ga4", "google_ads", "meta", "tiktok"]`; bu ayar boşken sitenin gönderdiği diğer platformlar da eklenir. `--platforms` ile aynıdır. |
 | `campaign_checks` | Varsayılan `true`. Her çalıştırma ilk sayfayı bir reklam tıklaması gibi açar (UTM parametreleri, `gclid`, `fbclid` ya da başlangıç adresinde zaten olanlar) ve bunların yönlendirmelerden geçip isteklere ulaştığını denetler. Düz adresi açmak için `false` yapın. |
 | `block_hits` | Varsayılan `true`. Takip isteklerinin gerçek uç noktalarınıza ulaşmasına izin vermek için `false` yapın. |
 | `consent_scenarios` | Varsayılan `true`. [Onay senaryolarını](#onay-senaryoları) atlamak için `false` yapın; her onay seçimi için başlangıç sayfasını bir kez ziyaret ederler. |
+| `baseline` | İsteğe bağlı: kabul edilen bulguların temel dosyasının, ayar dosyasına göre bağıl yolu. `--baseline` ile aynıdır. Bkz. [Bilinen bulguları kabul edin](#bilinen-bulguları-kabul-edin). |
 | `language` | Rapor dili, `en` (varsayılan) ya da `tr`. `--lang` ile aynıdır. |
 | `keep_bodies` | Varsayılan `false`. Takip isteklerini gönderildiği gibi, kullanıcı verisi gizlenmeden saklamak için `true` yapın. `--keep-bodies` ile aynıdır. |
 | `branding` | Varsayılan `true`. Analitik İşler logosunu ve "Generated by AI Tag Debugger · analitikisler.com" satırını raporlardan çıkarmak için `false` yapın. `--no-branding` ile aynıdır, ya da MCP `finish_audit` ve `run_audit` araçlarında `branding: false`. |
@@ -428,6 +472,8 @@ Bir yolculuk her iki görünümde de çalıştıysa yalnızca ilk görünümün
 | `base_url`, `model` | İsteğe bağlı: API adresi ve model kimliği, örneğin `openai-compatible` için. `--base-url` ve `--model` ile aynıdır. |
 | `notify` | İsteğe bağlı uyarılar, kayıtlı her çalıştırmadan sonra: `slack` (bir webhook adresi ya da `SLACK_WEBHOOK_URL` değişkenini okumak için `true`) ve `email` (bir adres ya da liste). Bkz. [Uyarılar](#uyarılar). |
 
+Ayar dosyası ve plan, okunur okunmaz, tarayıcı başlamadan önce denetlenir. Bir hata, alanı ve sabit bir seçim için izin verilen değerleri adlandırır, örneğin `viewports[1]: must be one of desktop, mobile (got "tablet")` ya da `journeys[0].steps[2].action: must be one of goto, click, fill, select, scroll, wait`. Aracın tanımadığı bir anahtar, en yakın olanı öneren bir uyarıyla yok sayılır (`Unknown key "viewport" ... Did you mean "viewports"?`); böylece dosyadaki fazladan bir not çalıştırmayı durdurmaz. `aitd plan` ile kaydedilen ve elektronik tablodan içe aktarılan planlar da aynı denetimden geçer.
+
 ### Uyarılar
 
 Kayıtlı her çalıştırmadan sonra `notify`, "Son çalıştırmadan bu yana değişenler" farkını ekibinize gönderir; böylece sitedeki bir değişiklik raporu açmadan size ulaşır:
@@ -442,9 +488,18 @@ Kayıtlı her çalıştırmadan sonra `notify`, "Son çalıştırmadan bu yana d
 - **Slack** webhook adresini alır. `"slack": true` ise adresi bunun yerine `SLACK_WEBHOOK_URL` ortam değişkeninden okur; böylece adres dosyada durmaz.
 - **E-posta** tek bir adres ya da bir liste alır. Postalar `SMTP_URL` içindeki sunucudan gönderilir, örneğin `smtps://kullanici:parola@mail.example.com:465`. Gönderen adresi `SMTP_FROM` belirler (varsayılan: ilk alıcı). `smtps://` kullanın; bağlantıyı baştan şifreler. Düz `smtp://` adresi giriş bilgisini ve postayı şifresiz gönderir, STARTTLS desteklenmez.
 
-Uyarı yalnızca kayıtlı bir çalıştırma için gönderilir (`--out` ile gönderilen için değil), karşılaştırılacak bir önceki çalıştırma varsa ve o zamandan beri bir değişiklik olduysa. Mesaj düzelen ve yeni sorunları listeler; konu satırı sayıları verir. Bir kanal başarısız olursa çalıştırma nedenini yazar ve devam eder. Çıkış kodu yine `--fail-on` ile belirlenir.
+Uyarı yalnızca kayıtlı bir çalıştırma için gönderilir (`--out` ile gönderilen için değil), karşılaştırılacak bir önceki çalıştırma varsa ve o zamandan beri bir değişiklik olduysa. Konu satırı önce sonucu, sonra sayıları ve başlığı taşır: `shop.example: Kaldı · 2 yeni sorun · purchase izlemesi bozuk (mobile)`. Gövde sonuç satırını yineler, sonra neyin düzeldiğini (*önceki durumuyla* birlikte) ve neyin yeni olduğunu listeler (her yeni kayıt önem düzeyi ve sorumlusuyla), ardından mini grafikli eğilim satırı, gelip giden sorunlar ve bir sorun 5, 10, 20 çalıştırmadır açık kaldığında (sonra her 10 çalıştırmada bir) "N çalıştırmadır hâlâ açık" satırı gelir; böylece aynı açık liste her mesajda tekrarlanmaz:
 
-## CLI
+```
+shop.example
+Sonuç: Kaldı · purchase izlemesi bozuk (mobile) · puan 25/100
+1 sorun düzeldi, 1 yeni sorun. 2026-10-15_1000 çalıştırmasıyla sağlık bulgularına göre karşılaştırıldı (2026-10-16_1000).
+- Düzeldi: GA4 page_view (önceki durum: Onaydan önce gönderildi)
+- Yeni: Meta Purchase · Bozuk · "Purchase" olayı "value" parametresi olmadan gönderildi. · Yazılımcı
+5 çalıştırmada eğilim (2026-10-12 → 2026-10-16): kötüleşiyor. Şimdi 2 bozuk · 1 risk · 0 uyarı; 3 çalıştırma önce 0 bozuk · 1 risk · 0 uyarı. `▃▃·▅█`
+```
+
+Eğilim tek başına hiçbir zaman uyarı tetiklemez. Bir kanal başarısız olursa çalıştırma nedenini yazar ve devam eder. Çıkış kodu yine `--fail-on` ile belirlenir.
 
 ## CLI
 
@@ -455,12 +510,15 @@ aitd plan list --site <url> [--data-dir <dir>]
 aitd plan import <dosya> --site <url> [--data-dir <dir>]
 aitd plan export <plan> --site <url> [--format xlsx|csv] [--data-dir <dir>]
 aitd run --site <url> (--against <plan> | --journey <id> | --goal "<metin>") [--config <dosya>] [--events <adlar>]
-         [--max-steps <n>] [--viewport desktop|mobile] [--platforms <liste>] [--data-dir <dir>]
+         [--max-steps <n>] [--viewport desktop|mobile] [--concurrency <n>] [--platforms <liste>] [--data-dir <dir>]
          [--provider anthropic|openai|gemini|openai-compatible] [--model <id>] [--lang en|tr] [--headed]
-         [--fail-on broken|risk|warning|never] [--scripted] [--no-ai] [--save-site <dir>] [--save-steps <dosya>]
+         [--fail-on broken|risk|warning|never] [--baseline <dosya>] [--update-baseline]
+         [--scripted] [--no-ai] [--save-site <dir>] [--save-steps <dosya>]
 aitd replay <dir>... [--update] [--out <dir>]
 aitd mcp [--http] [--port <n>] [--host <adres>] [--token <gizli>] [--public-url <https url>] [--reports <dir>]
          [--allow-private-network]
+aitd doctor [--site <url>] [--data-dir <dir>]
+aitd history --site <url> [--limit <n>] [--json] [--lang en|tr] [--data-dir <dir>]
 ```
 
 `aitd`, `ai-tag-debugger`'ın kısa bir takma adıdır ve aynı komutları ve seçenekleri kabul eder. Her komutun temel seçenekleri için `aitd <komut> --help` çalıştırın.
@@ -469,24 +527,29 @@ aitd mcp [--http] [--port <n>] [--host <adres>] [--token <gizli>] [--public-url
 
 | Seçenek | Komutlar | Anlamı |
 |---|---|---|
-| `--site <url>` | plan, run | Site. `plan` için zorunludur; `run` için `--against` ya da ayar dosyası siteyi vermiyorsa gereklidir. |
+| `--site <url>` | plan, run, doctor, history | Site. `plan` ve `history` için zorunludur; `run` için `--against` ya da ayar dosyası siteyi vermiyorsa gereklidir. `doctor` yalnızca adresin http(s) olduğunu ve ana makinesinin çözüldüğünü denetler. |
 | `--against <plan>` | run | Bir plana karşı kontrol: `latest` (ya da `last`), `first`, bir plan kimliği ya da bir plan dosyasının ya da klasörünün yolu. |
 | `--journey <id>` | run | Hazır bir yolculuk (tekrarlanabilir). |
 | `--goal "<metin>"` | run | Sade bir dille bir yolculuk (tekrarlanabilir). |
 | `--config <dosya>` | run | Siteyi, yolculukları ve planı bir ayar dosyasından al. |
 | `--events <adlar>` | run | Yalnızca bu event'leri kontrol et, örneğin `purchase,add_to_cart`. |
 | `--viewport <ad>` | run | `desktop` ya da `mobile` (tekrarlanabilir). |
+| `--concurrency <n>` | run | Aynı anda kaç yolculuğun çalışacağı, her biri kendi tarayıcısında: `1` (varsayılan) ile `8` arası. Yan yana çalışırken her yolculuğun günlük satırları `[yolculuk/görünüm]` ile başlar ve `--headed` o kadar tarayıcı penceresi açar. Ayar dosyasındaki `concurrency` ile aynıdır. |
 | `--platforms <liste>` | run | Kontrol edilecek platformlar, örneğin `ga4,meta`. Eski adı `--providers`'ın yerine geçer; o da bir minör sürüm daha çalışır. |
 | `--max-steps <n>` | plan, run | Yolculuk başına en fazla yapay zekâ adımı (`plan` için varsayılan 25). |
-| `--lang <kod>` | run | Rapor dili: `en` ya da `tr`. |
+| `--lang <kod>` | run, history | Rapor dili: `en` ya da `tr`. `history` için eğilim satırlarının dili. |
 | `--fail-on <düzey>` | run | Bu düzeyde çıkış kodu 1 olur: `broken` (varsayılan), `risk`, `warning` ya da `never`. |
+| `--baseline <dosya>` | run | Kabul edilen bulguların dosyası. Yine raporlanırlar, ama `--fail-on` için sayılmazlar. Bkz. [Bilinen bulguları kabul edin](#bilinen-bulguları-kabul-edin). |
+| `--update-baseline` | run | Bu çalıştırmanın her bulgusunu çalıştırmadan sonra temel dosyaya yaz; dosya yoksa oluştur. |
 | `--headed` | plan, run | Tarayıcı penceresini göster. |
 | `--provider <ad>`, `--model <id>` | plan, run | Yapay zekâ sağlayıcısı ve modeli. Varsayılan: ayarlı olan API anahtarı. |
-| `--scripted` | run | Her yolculuğun sabit adımlarını, yapay zekâ gezintisi olmadan tekrar oynat. |
+| `--scripted` | run | Her yolculuğun sabit adımlarını, yapay zekâ gezintisi olmadan tekrar oynat. Adımı olmayan bir yolculuk, sitenin son tamamlanan çalıştırmasının adımlarını tekrarlar. |
 | `--no-ai` | run | Hiç yapay zekâ modeli yok. `--scripted` anlamına gelir. |
 | `--save-site <dir>` | run | Sitenin yanıtlarını `replay` için kaydet. |
 | `--save-steps <dosya>` | run | Her yolculuğun attığı adımları bir ayar dosyasına yaz. |
-| `--data-dir <dir>` | plan, run | `aitd/` klasörünün (planlar ve çalıştırmalar) tutulduğu yer. Varsayılan: `./aitd`. `run --out` yerine geçer. |
+| `--data-dir <dir>` | plan, run, doctor, history | `aitd/` klasörünün (planlar ve çalıştırmalar) tutulduğu yer. Varsayılan: `./aitd`. `run --out` yerine geçer. |
+| `--limit <n>` | history | Eğilimin sitenin en yeni kaç çalıştırmasını okuyacağı. Varsayılan: 30. |
+| `--json` | history | Eğilim serisini, bulgu zaman çizelgesini ve yolculuk kararlılığını metin yerine JSON olarak yazdır. |
 | `--format xlsx\|csv` | plan export | Elektronik tablo biçimi. Varsayılan: `xlsx`. |
 | `--update` | replay | Bu tekrarın bulgularını beklenen bulgular yap. |
 | `--out <dir>` | replay | Tekrar raporlarının yazılacağı yer. `run` için `--out` gizli bir takma ad olarak bir minör sürüm daha çalışır ve bir not yazdırır; `--data-dir` kullanın. |
@@ -498,7 +561,32 @@ aitd mcp [--http] [--port <n>] [--host <adres>] [--token <gizli>] [--public-url
 
 0.10.0 sürümünde kaldırıldı: `plan --from`, `plan --out` ve `plan --force`. Plan taslağı her zaman yeni bir klasör kaydeder; kaldırılmış bir bayrak ne çalıştırılacağını yazdırır.
 
-Çıkış kodu, bulgular `--fail-on` düzeyine (varsayılan `broken`) ulaştığında `1` olur; böylece bir dağıtımı durdurabilir. Her dağıtımdan sonra çalıştırmak için [`examples/github-actions/ai-tag-debugger.yml`](examples/github-actions/ai-tag-debugger.yml) dosyasına bakın.
+Çıkış kodu, bulgular `--fail-on` düzeyine (varsayılan `broken`) ulaştığında `1` olur; böylece bir dağıtımı durdurabilir. Bir [temel dosyada](#bilinen-bulguları-kabul-edin) kabul edilen bulgular sayılmaz. Her dağıtımdan sonra çalıştırmak için [`examples/github-actions/ai-tag-debugger.yml`](examples/github-actions/ai-tag-debugger.yml) dosyasına bakın.
+
+**CI'da test sonuçları.** Her çalıştırma ayrıca `junit.xml` yazar: her yolculuk bir test paketi, her bulgu bir test vakasıdır ve `--fail-on` düzeyine ulaşan bulgu başarısız sayılır; böylece GitHub Actions, GitLab ve Jenkins bulguları test hataları olarak gösterir. GitHub Actions'ta dosyayı yükleyin ve bir JUnit raporlayıcı action'a verin:
+
+```yaml
+      - run: aitd run --config ai-tag-debugger.config.json --data-dir tracking-report
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: junit
+          path: tracking-report/**/junit.xml
+      # İsteğe bağlı: herhangi bir JUnit raporlayıcı action dosyayı çalıştırma üzerinde açıklamalara dönüştürür.
+      - uses: dorny/test-reporter@v2
+        if: always()
+        with:
+          name: tracking
+          path: tracking-report/**/junit.xml
+          reporter: java-junit
+```
+
+GitLab'da `artifacts: reports: junit:` ayarını aynı yola yönlendirin. Yanındaki `summary.json`, sayıları, sonucu (`status`: `fail`, `attention` ya da `pass`, ve `fail_broken` gibi bir `headline` anahtarı), veri kalitesi puanını (`score`, 0 ile 100 arası), kayıtlı çalıştırmalardaki eğilim yönünü (`direction`), yolculukları, her bulguyu (kontrol, önem düzeyi, platform, event, yolculuk, görünüm, başlık, mesaj), çalıştırma klasörünün adını `run` olarak ve diğer dosyaların adlarını o klasöre göre bağıl olarak `files` altında tutar; böylece bir betik, `capture.json` dosyasını ayrıştırmadan sonucu okuyabilir ve dosyadaki hiçbir şey çalıştırmanın yapıldığı makineye bağlı değildir:
+
+```sh
+jq '.counts.broken' aitd/example.com/runs/*/summary.json
+jq -r '.verdict.status + " " + (.score | tostring)' aitd/example.com/runs/*/summary.json
+```
 
 **Zamanlanmış çalıştırmalar.** Her dağıtımdan sonra değil de bir zamanlayıcıyla denetlemek için [`examples/github-actions/scheduled-run.yml`](examples/github-actions/scheduled-run.yml) dosyasını kullanın (varsayılan olarak haftalık; cron satırını değiştirebilirsiniz). Geçmişi çalıştırmalar arasında bir önbellekte saklar, böylece "Son çalıştırmadan beri değişenler" yeni bir runner'da da çalışır. Kendi sunucunuzda aynısı için [`examples/cron/`](examples/cron) içinde bir betik ve bir crontab satırı vardır.
 
@@ -516,9 +604,11 @@ aitd mcp [--http] [--port <n>] [--host <adres>] [--token <gizli>] [--public-url
 
   Event'ler ve istekler kaynağa göre filtrelenebilir. GA4 ürün dizgileri (`pr1`…) ve dataLayer `ecommerce.items` ürün kartları olarak gösterilir; özel ürün parametreleri kendi grubunda yer alır. Raporda betik yoktur: sekmeler ve filtreler düz HTML ve CSS'tir (Chrome 105, Safari 15.4 ya da Firefox 121 ve sonrası gerekir) ve yazdırırken her sekme görünür. Logolar gömülüdür, bu yüzden internetten hiçbir şey yüklenmez. `--no-branding`, Analitik İşler logosunu ve kredi satırını çıkarır.
 - `timeline.csv`: aynı zaman akışı, her isteğe, dataLayer gönderimine ve ağ çağrısına bir satır olarak; Excel ya da Google Sheets için hazır.
-- `report.md`: raporun Markdown hali, örneğin bir çekme isteği yorumu için.
-- `capture.json`: yakalanan her şey, kendi analiziniz için.
+- `report.md`: raporun Markdown hali; bir çekme isteği yorumu, bir Slack mesajı ya da bir e-posta için, dört yolculuklu bir çalıştırmada yaklaşık 100 satır ve 8 KB'ın altında. Başlığı sonuçtur (`# shop.example: purchase izlemesi bozuk (mobile)`), ardından tek bir meta satırı, veri kalitesi puanıyla birlikte durum ve sayılar gelir. Sonra sırasıyla: **Son çalıştırmadan bu yana değişenler** ve **Eğilim** (sitenin önceki çalıştırmaları varsa), **Plan ve site** (`--against` ile), **Öncelikler** (sorumlu başına yapılacaklar listesi: Yazılımcı, Tag Manager, Pazarlama), **Bulgular** (Nerede, Etkisi, Neden, Kanıt, Şurada sorunsuz, Sorumlu, Çözüm, Nasıl doğrulanır ve `report.html` içine bir bağlantıyla en fazla beş tam blok; geri kalanı *Ayrıca* altında birer satır), **Onay** (Consent Mode zamanlama cümlesi ve her hücresinde bir neden bulunan senaryo tablosu), **Sorunsuz olanlar**, **Yolculuklar** (çalıştırma başına bir satır, sonra yalnızca sorun taşıyan adımlar), **Kontrol edilmeyenler** (çalıştırmanın yargılayamadıkları, bunu açan ayar anahtarıyla birlikte) ve **Etiket envanteri**. İstek başına zaman akışı dosyada yoktur; `timeline.csv` içindedir.
+- `capture.json`: yakalanan her şey, kendi analiziniz için; aracın `version` bilgisi, `ai` sağlayıcısı ve hesaplanan `metrics` (sonuç, puan, plan kapsamı, huni, platform tutarlılığı, onay uyumu, dönüşüm bütünlüğü, zamanlama, öncelikler) dahil.
 - `plan-check.json`: `--against` ile, planlanan her event için kovasıyla birlikte bir kayıt.
+- `junit.xml`: bulgular JUnit test sonuçları olarak, yolculuk ve görünüm başına bir paket; CI sistemlerinin test hatası olarak göstermesi için (yukarıya bakın).
+- `summary.json`: çalıştırmanın sayıları, sonucu, puanı, eğilim yönü, yolculukları, bulguları ve dosya adları, betikler için tek bir küçük dosyada.
 - `plan.html` (planın klasöründe): planın event'lerini, parametrelerini ve kullanıcı özelliklerini gösteren okunabilir bir sayfa.
 
 Raporlar bir kredi satırıyla biter: "Generated by AI Tag Debugger · analitikisler.com"; alan adı düz bir bağlantıdır (görsel yok, takip yok ve yönlendiren bilgisi yok; böylece rapor adresleri sızdırılmaz). `--no-branding`, bunu logosuyla birlikte kaldırır.
@@ -539,7 +629,7 @@ Sunucunun sunduğu araçlar:
 | `browser_action` | Tek bir tıklama, doldurma, seçme, gitme, kaydırma ya da bekleme. Sayfayı ve o adımın gönderdiği takip isteklerini döndürür. |
 | `get_page` | Geçerli sayfayı gösterir. |
 | `finish_audit` | Her şeyi ölçümleme planınıza (JSON) ya da `against` olarak verilen kayıtlı bir plana (`latest`, `first`, bir plan kimliği ya da yerel bir sunucuda bir yol) ya da hazır yolculuğun event'lerine karşı kontrol eder; isterseniz yalnızca adını verdiğiniz `events` için, ve zaman akışıyla birlikte tam HTML raporunu yazar. Site denetimden alınır. |
-| `run_audit` | Bir ayar dosyasını baştan sona çalıştırır. `against` ile çalıştırmayı kayıtlı bir plana karşı kontrol eder; ayar dosyasında yolculuk yoksa, plandan türetilen yolculukları gezer. Dosya yolları yalnızca yerelde çalışır. |
+| `run_audit` | Bir ayar dosyasını baştan sona çalıştırır. `against` ile çalıştırmayı kayıtlı bir plana karşı kontrol eder; ayar dosyasında yolculuk yoksa, plandan türetilen yolculukları gezer. `concurrency` o kadar yolculuğu aynı anda, her birini kendi tarayıcısında çalıştırır (varsayılan 1); `baseline`, `--update-baseline` ile yazılmış kabul edilen bulgular dosyasını adlandırır (varsayılan: ayar dosyasındaki `baseline`; bkz. [Bilinen bulguları kabul edin](#bilinen-bulguları-kabul-edin)). Dosya yolları yalnızca yerelde çalışır. |
 
 `against`, CLI'deki `--against` ile aynı değerleri alır. HTTP üzerinden yalnızca `latest`, `first` ya da bir plan kimliği kabul edilir, asla bir yol değil. Planlar, `aitd plan --site <url>` ya da `make_plan` ile kaydedilmiş olanlardır. Neyin takip edileceğini öğrenmek için plan, sitenin ne gönderdiğini öğrenmek için denetim isteyin.
 
@@ -615,6 +705,8 @@ Tünel gerektirmeyen barındırılmış bir sunucu, [Analitik İşler](https://a
 ```bash
 npm run setup   # Node'u denetler, bağımlılıkları ve Chromium'u kurar, bir AI sağlayıcı anahtarının ayarlı olup olmadığını söyler
 npm test        # ayrıştırıcılar, kontroller, her AI sağlayıcısı ve MCP sunucusu; demo mağazaya karşı uçtan uca
+npm run test:unit   # yalnızca tarayıcı gerektirmeyen testler, yaklaşık on saniyede
+npm run lint    # ESLint, yalnızca önerilen kurallar: tanımsız adlar, kullanılmayan import'lar ve benzerleri
 ```
 
 Depoda ayrıca bir geliştirme konteyneri (`.devcontainer/devcontainer.json`) vardır. VS Code'da Dev Containers eklentisiyle ya da GitHub Codespaces'te açın; Chromium'un sistem kütüphaneleri dahil `npm run setup`'ı sizin yerinize çalıştırır. Oradaki bir AI modelini kullanmak için anahtarınızı bir Codespaces sırrı olarak ekleyin ya da konteynerin terminalinde dışa aktarın.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
   "mcpName": "io.github.analitikisler/ai-tag-debugger",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Open-source AI agent that QA-tests your website's analytics, ad and consent tracking (GA4, GTM, Google Ads, Meta, TikTok). Bring your own model (Claude, OpenAI, Gemini) or use it from your chat app over MCP.",
   "type": "module",
   "bin": {
@@ -17,6 +17,8 @@
   "scripts": {
     "setup": "node scripts/setup.js",
     "test": "node --test test/*.test.js",
+    "test:unit": "node --test test/campaign.test.js test/changes.test.js test/ci-output.test.js test/checks.test.js test/consent-scenarios.test.js test/doctor.test.js test/gtm.test.js test/history-cli.test.js test/history.test.js test/i18n.test.js test/inventory.test.js test/journeys.test.js test/learn.test.js test/metrics.test.js test/notify.test.js test/parsers.test.js test/plan-check.test.js test/plan-html.test.js test/plan.test.js test/report-md.test.js test/report.test.js test/schema.test.js test/server-json.test.js test/server-side.test.js test/setup.test.js test/workspace.test.js",
+    "lint": "eslint .",
     "demo:serve": "node examples/serve.js",
     "demo": "node src/cli.js run --config examples/demo.config.json --scripted --no-ai"
   },
@@ -60,5 +62,10 @@
   },
   "optionalDependencies": {
     "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "eslint": "^9.39.5",
+    "globals": "^17.13.0"
   }
 }

package/src/agent.js

@@ -120,7 +120,7 @@ function withTimeout(promise, ms, message) {
  *   timeouts: milliseconds for one model answer, one browser action and one read of the page.
  */
 export async function runAgentJourney(session, journey, opts = {}) {
-  const provider = opts.provider ?? (await createProvider({ name: opts.providerName, model: opts.model, client: opts.client }));
+  const provider = opts.provider ?? (await createProvider({ name: opts.providerName, model: opts.model, client: opts.client, log: opts.log }));
   const maxSteps = opts.maxSteps ?? 30;
   const log = opts.log ?? (() => {});
   const limit = { ...TIMEOUTS, ...opts.timeouts };
@@ -170,14 +170,21 @@ export async function runAgentJourney(session, journey, opts = {}) {
   return { completed: false, note: `Stopped after ${maxSteps} steps without reaching the goal.` };
 }
 
-/** Replays fixed steps from the config, without calling an AI model. */
+/**
+ * Replays fixed steps from the config, without calling an AI model. journey.stepsFrom names the earlier
+ * run the steps were taken from when the journey has none of its own (see lastSteps in replay.js).
+ */
 export async function runScriptedJourney(session, journey, opts = {}) {
   const log = opts.log ?? (() => {});
   if (!journey.steps?.length && !journey.incomplete) throw new Error(`Journey "${journey.id}" has no "steps" for --scripted mode.`);
   for (const step of journey.steps ?? []) {
     log(`  ${step.reason ?? `${step.action} ${step.selector ?? step.url ?? ""}`}`);
     const error = await session.act(step);
-    if (error && !step.optional) return { completed: false, note: `Step "${step.reason ?? step.action}" failed: ${error}` };
+    if (error && !step.optional) {
+      const failed = `Step "${step.reason ?? step.action}" failed: ${error}`;
+      // Saved steps stop fitting when the site changes; only a model can find the new way through.
+      return { completed: false, note: journey.stepsFrom ? `${failed} The steps saved by run ${journey.stepsFrom} no longer fit the site. Run the journey with an AI model once to save new ones.` : failed };
+    }
   }
   // Tags often send a moment after the last click (GA4 batches events). An AI run gives them that time
   // while the model answers; a scripted run would otherwise close the browser first.
@@ -197,7 +204,7 @@ export async function runJourney(config, journey, viewport, opts = {}) {
   const har = (dir) => (dir ? path.join(dir, harName(journey.id, viewport)) : undefined);
   const session = new AuditSession({
     viewport, site: config.site, allowedHosts: config.allowed_hosts, providers: config.providers, detect: config.detect_providers, keepBodies: config.keep_bodies === true,
-    blockHits: config.block_hits !== false, headless: !opts.headed, recordHar: har(opts.saveSite), replayHar: har(opts.replaySite),
+    blockHits: config.block_hits !== false, headless: !opts.headed, recordHar: har(opts.saveSite), replayHar: har(opts.replaySite), log: opts.log,
   });
   try {
     await session.start();