@analitikisler/ai-tag-debugger 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.11.0 (2026-10-16)
+
+- Every saved run is compared with the site's previous run. The report opens with a "Changed since last run" section (`2 events fixed, 1 new problem`) that lists what was fixed and what is new, by plan coverage when both runs used `--against` and by health findings otherwise. The first run says there is nothing to compare yet. No new flag; the result is also in `capture.json` under `changes`.
+- A plain sentence can be a request: `aitd "check my GA tags"`. The sentence becomes a fixed command through the AI provider, or a keyword matcher when no key is set. aitd prints the command and asks before running it; `-y` skips the question. An unclear sentence gets one short question back. A sentence that names no journey, goal or plan asks what to test, and suggests the site's latest plan when it has one.
+- `aitd plan --topic <name>` limits a plan to one kind of event: `custom-events`, `ecommerce`, `forms` or `consent`. Sentences such as "what custom events does my site need" use it.
+- The MCP server has a `make_plan` tool that drafts a tracking plan for a site, with an optional topic. Chat apps use it when a user asks what a site should track, and `run_audit` or `finish_audit` checks the audit against the plan.
+
 ## 0.10.0 (2026-10-16)
 
 - Plan, then audit. `aitd plan --site <url>` drafts a measurement plan in its own folder, `aitd/<domain>/plans/<id>/`: the events a site should send, with a description, the page and element that trigger each one, its parameters (custom ones marked) with example values, and suggested user properties. Events the site already sends are marked `seen`. It browses one page of each type (home, a category, a product, cart, first checkout step, search, sign-up and contact forms) without paying or submitting personal details, and prints the page types it found and the ones the site doesn't have.

package/README.md

@@ -141,6 +141,33 @@ No API key yet? Replay the fixed steps without any AI model:
 node src/cli.js run --config examples/demo.config.json --scripted --no-ai --data-dir reports/demo
 ```
 
+## Just ask
+
+You don't have to learn the options first. Put a plain sentence in quotes and aitd turns it into the matching command, prints that command and asks `Run this? (Y/n)` before it runs anything:
+
+```bash
+aitd "check my google analytics tags"
+# aitd run --platforms ga4
+# Run this? (Y/n)
+```
+
+| You type | aitd runs |
+|---|---|
+| `"Check my google analytics tags"` | `aitd run --platforms ga4` |
+| `"What changed on my site since the last run"` | `aitd run` (every run already reports what changed) |
+| `"Compare my site against the plan"` | `aitd run --against latest` |
+| `"What custom events does my site need"` | `aitd plan --topic custom-events` |
+| `"Is my Meta pixel firing on checkout?"` | `aitd run --platforms meta --goal "reach checkout"` |
+| `"Test signing up for the newsletter"` | `aitd run --goal "sign up for the newsletter"` |
+| `"Does my purchase event send the right revenue?"` | `aitd run --journey purchase` |
+| `"Make a tracking plan for example.com"` | `aitd plan --site https://example.com` |
+| `"What ecommerce events should an online shop track?"` | `aitd plan --topic ecommerce` |
+| `"Check TikTok and Google Ads on the contact form"` | `aitd run --platforms google_ads,tiktok --goal "submit the contact form"` |
+
+Add `-y` to skip the question: `aitd -y "check my google analytics tags"`.
+
+If a sentence leaves something out, aitd asks one short question instead of guessing: plan or run, which site, or what to test. Reports can't be filtered from a sentence yet (`"Show me only the errors from the last report"` says so). Without an AI key, a small keyword matcher handles the common phrases. With one, the AI reads any wording, but it can only pick options that exist, so it never invents a flag.
+
 ## Plan, then audit
 
 A run checks what a site sends against a **plan**: the events, parameters and user properties you expect. Three steps:
@@ -159,6 +186,12 @@ aitd run --site https://yoursite.com --against latest
 
 **Drafting a plan** needs no tracking code. The AI explores one page of each type: the home page, a category, a product, the cart, the first checkout step, search, and any sign-up or contact forms. It never pays, and it never submits a form with personal details. `--provider`, `--model` and `--max-steps` (default 25, the most AI steps) work as they do for `run`. The output prints "Page types found" and "Not present on this site", so you can see which page types the AI reached. A small site, with only 2 pages, is fine.
 
+To draft a plan for one kind of event only, add `--topic`: `custom-events`, `ecommerce`, `forms` or `consent`. The plan then covers just those events, and the rest of the plan format is unchanged:
+
+```bash
+aitd plan --site https://yoursite.com --topic ecommerce
+```
+
 The plan is saved in a new folder, `aitd/<domain>/plans/<id>/`, as `measurement-plan.json` and a readable `plan.html`. For each event it lists:
 
 - `name` and `platform`. Events specific to your site, such as a size guide or a store locator, are marked `custom: true`.
@@ -224,6 +257,8 @@ aitd/
 
 An ID is the local time, `YYYY-MM-DD_HHMM`. When that minute is already taken, seconds are added (`_HHMMSS`). Nothing is ever replaced: each draft, import and run gets a new folder. Use `--data-dir <dir>` to keep the `aitd/` folder somewhere else. `replay` and `--save-site` folders are not affected.
 
+Each report opens with a "Changed since last run" section that compares the run with the site's previous one in `runs/`, for example `2 events fixed, 1 new problem`, and lists each one. When both runs used `--against`, it compares plan coverage (an event that went from Missing to Implemented is fixed); otherwise it compares the health findings. The first run for a site says there is nothing to compare yet. There is no flag to set. The comparison is also saved under `changes` in `capture.json`.
+
 ## Choose what to test
 
 You don't need a config file to start. Pick ready-made journeys, describe your own in plain language, check against a plan, and narrow the check to the events you care about:
@@ -331,7 +366,8 @@ When a journey ran on both viewports, only the first viewport's steps are kept.
 ## CLI
 
 ```
-aitd plan --site <url> [--headed] [--provider <name>] [--model <id>] [--max-steps <n>] [--data-dir <dir>]
+aitd "<sentence>" [-y]
+aitd plan --site <url> [--topic <name>] [--headed] [--provider <name>] [--model <id>] [--max-steps <n>] [--data-dir <dir>]
 aitd plan list --site <url> [--data-dir <dir>]
 aitd plan import <file> --site <url> [--data-dir <dir>]
 aitd plan export <plan> --site <url> [--format xlsx|csv] [--data-dir <dir>]
@@ -411,13 +447,14 @@ Tools the server offers:
 
 | Tool | What it does |
 |---|---|
+| `make_plan` | Drafts a tracking plan for a site (what should be tracked), the same as `aitd plan --site`. Pass `topic` (`custom-events`, `ecommerce`, `forms`, `consent`) to limit it to one kind of event. The plan is saved and its ID can be given as `against` to `finish_audit`. It uses the AI provider configured on the computer that runs the server and takes a few minutes. |
 | `start_audit` | Opens a fresh browser on a URL and starts recording all tracking. Pass a ready-made journey (`purchase`, `sign_up`, …) to get its goal and expected events, and `providers` to choose the platforms to check. The assistant asks you which platforms to check first. |
 | `browser_action` | One click, fill, select, goto, scroll or wait. Returns the page and the tracking hits that step sent. |
 | `get_page` | Shows the current page. |
 | `finish_audit` | Checks everything against your measurement plan (JSON), a saved one given as `against` (`latest`, `first`, a plan ID, or on a local server a path), or the ready-made journey's events, optionally only the `events` you name, and writes the full HTML report with the timeline. The site comes from the audit. |
 | `run_audit` | Runs a config file end to end. With `against`, it checks the run against a saved plan and, when the config has no journeys, walks the journeys derived from that plan. Local only for file paths. |
 
-`against` takes the same values as the CLI's `--against`. Over HTTP it takes only `latest`, `first` or a plan ID, never a path. Plans are the ones saved by `aitd plan --site <url>`.
+`against` takes the same values as the CLI's `--against`. Over HTTP it takes only `latest`, `first` or a plan ID, never a path. Plans are the ones saved by `aitd plan --site <url>` or by `make_plan`. Ask for a plan when you want to know what to track, and for an audit when you want to know what the site sends.
 
 The browser runs on the computer where the server runs, so it can reach your staging and `localhost` sites. Tracking requests are answered locally as usual.
 

package/README.tr.md

@@ -141,6 +141,33 @@ Henüz bir API anahtarınız yok mu? Sabit adımları hiçbir yapay zekâ modeli
 node src/cli.js run --config examples/demo.config.json --scripted --no-ai --data-dir reports/demo
 ```
 
+## Sadece sorun
+
+Önce tüm seçenekleri öğrenmeniz gerekmez. Tırnak içinde düz bir cümle yazın; aitd bunu eşleşen komuta çevirir, komutu gösterir ve çalıştırmadan önce `Run this? (Y/n)` diye sorar:
+
+```bash
+aitd "check my google analytics tags"
+# aitd run --platforms ga4
+# Run this? (Y/n)
+```
+
+| Yazdığınız | aitd çalıştırır |
+|---|---|
+| `"Check my google analytics tags"` | `aitd run --platforms ga4` |
+| `"What changed on my site since the last run"` | `aitd run` (her çalıştırma neyin değiştiğini zaten raporlar) |
+| `"Compare my site against the plan"` | `aitd run --against latest` |
+| `"What custom events does my site need"` | `aitd plan --topic custom-events` |
+| `"Is my Meta pixel firing on checkout?"` | `aitd run --platforms meta --goal "reach checkout"` |
+| `"Test signing up for the newsletter"` | `aitd run --goal "sign up for the newsletter"` |
+| `"Does my purchase event send the right revenue?"` | `aitd run --journey purchase` |
+| `"Make a tracking plan for example.com"` | `aitd plan --site https://example.com` |
+| `"What ecommerce events should an online shop track?"` | `aitd plan --topic ecommerce` |
+| `"Check TikTok and Google Ads on the contact form"` | `aitd run --platforms google_ads,tiktok --goal "submit the contact form"` |
+
+Soruyu atlamak için `-y` ekleyin: `aitd -y "check my google analytics tags"`.
+
+Bir cümlede bir şey eksikse aitd tahmin yürütmek yerine tek bir kısa soru sorar: plan mı çalıştırma mı, hangi site, ya da neyin test edileceği. Rapor filtreleme henüz cümleyle yapılamaz (`"Show me only the errors from the last report"` bunu söyler). Yapay zekâ anahtarı yoksa, yaygın ifadeleri küçük bir anahtar sözcük eşleştirici karşılar. Anahtar varsa yapay zekâ her ifadeyi anlar, ama yalnızca var olan seçenekleri seçebilir; bu yüzden var olmayan bir bayrak uydurmaz. Örnek cümleler İngilizcedir, çünkü anahtar sözcük eşleştirici İngilizce ifadeleri tanır.
+
 ## Planla, sonra denetle
 
 Bir çalıştırma, sitenin gönderdiklerini bir **plan** ile karşılaştırır: beklediğiniz event'ler, parametreler ve kullanıcı özellikleri. Üç adım:
@@ -159,6 +186,12 @@ aitd run --site https://yoursite.com --against latest
 
 **Plan taslağı çıkarmak** takip kodu gerektirmez. Yapay zekâ her sayfa türünden birer sayfayı inceler: ana sayfa, bir kategori, bir ürün, sepet, ilk ödeme adımı, arama ve varsa üyelik ya da iletişim formları. Asla ödeme yapmaz ve kişisel bilgilerle bir formu göndermez. `--provider`, `--model` ve `--max-steps` (varsayılan 25, yapay zekâ için en fazla adım) `run` için olduğu gibi çalışır. Çıktı "Bulunan sayfa türleri" ve "Bu sitede yok" satırlarını yazdırır, böylece yapay zekânın hangi sayfa türlerine ulaştığını görürsünüz. Yalnızca 2 sayfası olan küçük bir site de sorun değildir.
 
+Yalnızca bir tür event için plan çıkarmak istiyorsanız `--topic` ekleyin: `custom-events`, `ecommerce`, `forms` ya da `consent`. Plan yalnızca bu event'leri kapsar, plan biçimi değişmez:
+
+```bash
+aitd plan --site https://yoursite.com --topic ecommerce
+```
+
 Plan, yeni bir klasöre, `aitd/<alan adı>/plans/<id>/` içine `measurement-plan.json` ve okunabilir bir `plan.html` olarak kaydedilir. Her event için şunları listeler:
 
 - `name` ve `platform`. Sitenize özgü event'ler, örneğin bir beden rehberi ya da mağaza bulucu, `custom: true` ile işaretlenir.
@@ -224,6 +257,8 @@ aitd/
 
 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.
+
 ## Ne test edileceğini seçin
 
 Başlamak için bir ayar dosyasına ihtiyacınız yok. Hazır yolculukları seçin, kendi yolculuğunuzu sade bir dille tarif edin, bir plana karşı kontrol edin ve kontrolü yalnızca ilgilendiğiniz event'lerle sınırlayın:
@@ -331,7 +366,8 @@ Bir yolculuk her iki görünümde de çalıştıysa yalnızca ilk görünümün
 ## CLI
 
 ```
-aitd plan --site <url> [--headed] [--provider <ad>] [--model <id>] [--max-steps <n>] [--data-dir <dir>]
+aitd "<cümle>" [-y]
+aitd plan --site <url> [--topic <ad>] [--headed] [--provider <ad>] [--model <id>] [--max-steps <n>] [--data-dir <dir>]
 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>]
@@ -411,13 +447,14 @@ Sunucunun sunduğu araçlar:
 
 | Araç | Ne yapar |
 |---|---|
+| `make_plan` | Bir site için takip planı çıkarır (neyin takip edilmesi gerektiği), `aitd plan --site` ile aynıdır. Yalnızca bir tür event için sınırlamak üzere `topic` verin (`custom-events`, `ecommerce`, `forms`, `consent`). Plan kaydedilir ve kimliği `finish_audit` için `against` olarak verilebilir. Sunucuyu çalıştıran bilgisayarda ayarlı yapay zekâ sağlayıcısını kullanır ve birkaç dakika sürer. |
 | `start_audit` | Bir URL'de yeni bir tarayıcı açar ve tüm takibi kaydetmeye başlar. Hedefini ve beklenen event'lerini almak için hazır bir yolculuk (`purchase`, `sign_up`, …) verin; kontrol edilecek platformları seçmek için `providers` verin. Asistan önce hangi platformların kontrol edileceğini size sorar. |
 | `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. |
 
-`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>` ile kaydedilmiş olanlardı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.
 
 Tarayıcı, sunucunun çalıştığı bilgisayarda çalışır; bu yüzden staging ve `localhost` sitelerinize erişebilir. Takip istekleri her zamanki gibi yerelde yanıtlanır.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
   "mcpName": "io.github.analitikisler/ai-tag-debugger",
-  "version": "0.10.0",
+  "version": "0.11.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": {

package/src/ask.js

@@ -0,0 +1,123 @@
+// Turns a plain sentence like "check my GA tags" into an aitd command.
+// The AI provider fills a fixed intent schema, so it can never invent options;
+// without an AI key a small keyword matcher handles the common phrases.
+import { PROVIDERS as PLATFORMS } from "./parsers.js";
+
+const PLATFORM_KEYS = Object.keys(PLATFORMS);
+// The same values as plan --topic (TOPICS in discover.js, kept in step by a test).
+export const TOPIC_KEYS = ["custom-events", "ecommerce", "forms", "consent"];
+
+export const INTENT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["action", "site", "against", "platforms", "goal", "journey", "topic", "question"],
+  properties: {
+    action: { type: "string", enum: ["plan", "run", "report", "unclear"], description: "plan drafts what a site should track; run audits what the site sends; report re-reads an existing report; unclear when you cannot tell plan from run." },
+    site: { type: ["string", "null"], description: "The site's domain or URL if the sentence names one." },
+    against: { type: ["string", "null"], enum: ["plan", "latest", null], description: "run only: compare with the saved plan, or with the latest run (\"what changed\", \"since the last run\", \"after the deploy\")." },
+    platforms: { type: "array", items: { type: "string", enum: PLATFORM_KEYS }, description: "Only the tracking platforms the sentence names; empty for all." },
+    goal: { type: ["string", "null"], description: "run only: a short user journey to try, in plain words, e.g. \"submit the contact form\"." },
+    journey: { type: ["string", "null"], enum: ["purchase", null], description: "run only: purchase when the sentence is about the purchase event or revenue." },
+    topic: { type: ["string", "null"], enum: [...TOPIC_KEYS, null], description: "plan only: limit the plan to one kind of event when the sentence asks about it." },
+    question: { type: ["string", "null"], description: "One short question to ask back when the sentence is ambiguous; otherwise null." },
+  },
+};
+
+const SYSTEM = `You translate a request about website tracking (analytics, ads, consent tags) into options for the aitd command line tool. Fill the schema with only what the sentence says; leave the rest null or empty. Use action "unclear" and a short question when you cannot tell whether the user wants a tracking plan or an audit of the live site.`;
+
+const has = (s, re) => re.test(s);
+
+/** The intent for a sentence from keywords alone, for when no AI key is set. */
+export function matchKeywords(sentence) {
+  const s = ` ${sentence.toLowerCase()} `;
+  const intent = { action: null, site: null, against: null, platforms: [], goal: null, journey: null, topic: null, question: null };
+  const site = sentence.match(/\b(?:https?:\/\/)?((?:[a-z0-9-]+\.)+[a-z]{2,})(?:\/\S*)?/i);
+  if (site) intent.site = site[1].toLowerCase();
+
+  if (has(s, /google analytics|\bga4?\b/)) intent.platforms.push("ga4");
+  if (has(s, /google ads|adwords/)) intent.platforms.push("google_ads");
+  if (has(s, /\bmeta\b|facebook/)) intent.platforms.push("meta");
+  if (has(s, /tiktok/)) intent.platforms.push("tiktok");
+
+  if (has(s, /only the (errors|failures)|from the (last|latest) report/)) intent.action = "report";
+  else if (has(s, /tracking plan|make a plan|should .* track|does my site need|events .* need/)) intent.action = "plan";
+  else {
+    if (has(s, /since (the )?last run|what changed|\bbreak|\bbroke|deploy/)) intent.against = "latest";
+    else if (has(s, /(against|in) the plan/)) intent.against = "plan";
+    if (has(s, /revenue|purchase event/)) intent.journey = "purchase";
+    else if (has(s, /newsletter/)) intent.goal = "sign up for the newsletter";
+    else if (has(s, /accept(ing)? (the )?cookies|consent/)) intent.goal = "browse without accepting cookies";
+    else if (has(s, /contact form/)) intent.goal = "submit the contact form";
+    else if (has(s, /checkout/)) intent.goal = "reach checkout";
+    if (intent.platforms.length || intent.against || intent.goal || intent.journey || has(s, /\b(check|test|audit|firing|fire|working)\b/)) intent.action = "run";
+  }
+  if (intent.action === "plan") {
+    if (has(s, /custom events?/)) intent.topic = "custom-events";
+    else if (has(s, /ecommerce|e-commerce|online shop|\bshop\b|\bstore\b/)) intent.topic = "ecommerce";
+    else if (has(s, /\bforms?\b/)) intent.topic = "forms";
+    else if (has(s, /consent|cookies?/)) intent.topic = "consent";
+  }
+  if (!intent.action) {
+    intent.action = "unclear";
+    intent.question = "Do you want a tracking plan or a check of what the site sends? (plan/run)";
+  }
+  return intent;
+}
+
+/** Asks the provider for the intent of a sentence; falls back to keywords without one. */
+export async function translate(sentence, { provider } = {}) {
+  if (!provider) return { intent: matchKeywords(sentence), by: "keywords" };
+  const result = await provider.json({ system: SYSTEM, texts: [sentence], schema: INTENT_SCHEMA });
+  if (result.error) return { intent: matchKeywords(sentence), by: "keywords" };
+  return { intent: normalize(result.value), by: "ai" };
+}
+
+/** Keeps only schema values, so an odd reply can never become an option. */
+export function normalize(v = {}) {
+  const str = (x) => (typeof x === "string" && x.trim() ? x.trim() : null);
+  return {
+    action: ["plan", "run", "report", "unclear"].includes(v.action) ? v.action : "unclear",
+    site: str(v.site),
+    against: ["plan", "latest"].includes(v.against) ? v.against : null,
+    platforms: [...new Set((Array.isArray(v.platforms) ? v.platforms : []).filter((p) => PLATFORM_KEYS.includes(p)))],
+    goal: str(v.goal),
+    journey: v.journey === "purchase" ? "purchase" : null,
+    topic: TOPIC_KEYS.includes(v.topic) ? v.topic : null,
+    question: str(v.question),
+  };
+}
+
+const siteUrl = (site) => (/^https?:\/\//i.test(site) ? site : `https://${site}`);
+
+/** The aitd arguments for an intent, or { question } when one more answer is needed. */
+export function intentToArgs(intent) {
+  if (intent.action === "unclear") return { question: intent.question ?? "Do you want a tracking plan or a check of what the site sends? (plan/run)" };
+  if (intent.action === "report") return { unsupported: "Filtering an existing report is not available yet. Open the latest report in aitd/<domain>/runs/." };
+  const args = [intent.action];
+  if (intent.site) args.push("--site", siteUrl(intent.site));
+  if (intent.action === "plan" && intent.topic) args.push("--topic", intent.topic);
+  if (intent.action === "run") {
+    // --against takes a saved plan. Every run already reports what changed since the previous
+    // run, so "since the last run" needs no option of its own.
+    if (intent.against === "plan") args.push("--against", "latest");
+    if (intent.platforms.length) args.push("--platforms", intent.platforms.join(","));
+    if (intent.journey) args.push("--journey", intent.journey);
+    if (intent.goal) args.push("--goal", intent.goal);
+  }
+  return { args };
+}
+
+/** True when a run has nothing to test yet: no plan to check against, no journey, no goal. */
+export function needsWhatToTest(args) {
+  return args[0] === "run" && !["--against", "--journey", "--goal"].some((o) => args.includes(o));
+}
+
+/** The command as the user would type it. */
+export function commandText(args) {
+  return ["aitd", ...args.map((a) => (/^[\w.,:/@=-]+$/.test(a) ? a : `"${a.replace(/(["\\$`])/g, "\\$1")}"`))].join(" ");
+}
+
+/** True when the arguments are one sentence rather than a command. */
+export function isSentence(positionals) {
+  return positionals.length === 1 && /\s/.test(positionals[0].trim());
+}

package/src/audit.js

@@ -1,6 +1,7 @@
 // A full audit from a config file: run every journey, check, explain, write the reports.
 // Shared by the CLI and the MCP server's run_audit tool.
 import { newRunDir } from "./workspace.js";
+import { compareRuns, previousRun } from "./changes.js";
 import { readFile, mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { failedRun, runJourney } from "./agent.js";
@@ -34,18 +35,23 @@ export async function loadConfig(configFile) {
 }
 
 
-/** Writes report.md, report.html, timeline.csv and capture.json, plus plan-check.json with --against. */
-export async function writeReports({ outDir, config, plan, runs, findings, explained, lang, against = null, branding = config.branding !== false }) {
+/**
+ * Writes report.md, report.html, timeline.csv and capture.json, plus plan-check.json with --against.
+ * previous: the site's last saved run (see previousRun), null when there is none, or undefined to skip
+ * the "Changed since last run" section.
+ */
+export async function writeReports({ outDir, config, plan, runs, findings, explained, lang, against = null, branding = config.branding !== false, previous = undefined }) {
   await mkdir(outDir, { recursive: true });
   const title = messages(lang).ui.title(new URL(config.site).hostname);
   const generatedAt = new Date().toISOString().slice(0, 16).replace("T", " ") + " UTC";
   const check = against ? { plan_id: against.id ?? null, ...planCheck(plan, runs, findings) } : null;
-  const report = { title, generatedAt, findings, explained, runs, plan, lang, branding, against: against?.label ?? null, planCheck: check };
+  const changes = previous === undefined ? null : compareRuns(previous, { findings, planCheck: check });
+  const report = { title, generatedAt, findings, explained, runs, plan, lang, branding, against: against?.label ?? null, planCheck: check, changes };
   await writeFile(path.join(outDir, "report.md"), renderMarkdown(report));
   await writeFile(path.join(outDir, "report.html"), renderHtml(report));
   await writeFile(path.join(outDir, "timeline.csv"), renderCsv(report));
   if (check) await writeFile(path.join(outDir, "plan-check.json"), JSON.stringify(check, null, 2));
-  await writeFile(path.join(outDir, "capture.json"), JSON.stringify({ config: { ...config, plan }, ...(against ? { against: { plan_id: against.id, file: against.file } } : {}), runs, findings, explained }, null, 2));
+  await writeFile(path.join(outDir, "capture.json"), JSON.stringify({ config: { ...config, plan }, ...(against ? { against: { plan_id: against.id, file: against.file } } : {}), runs, findings, explained, ...(changes ? { changes } : {}) }, null, 2));
   return path.join(outDir, "report.html");
 }
 
@@ -130,8 +136,10 @@ export async function runAudit(opts) {
     explained = await explainFindings({ findings, plan, runs, gtmContainer, provider, lang, log });
   }
 
+  // Runs saved in the site's runs folder are compared with the one before; a run sent to --out is not.
+  const previous = opts.outDir ? undefined : await previousRun(opts.dataDir, config.site);
   const outDir = path.resolve(opts.outDir ?? (await newRunDir(opts.dataDir, config.site)).dir);
-  const reportPath = await writeReports({ outDir, config, plan, runs, findings, explained, lang, against, branding: opts.branding ?? config.branding !== false });
+  const reportPath = await writeReports({ outDir, config, plan, runs, findings, explained, lang, against, branding: opts.branding ?? config.branding !== false, previous });
   const counts = summarize(groupFindings(findings));
   return { journeys, plan, runs, findings, explained, counts, reportPath, outDir, lang, ...(against ? { againstId: against.id } : {}), ...(saveError ? { saveError } : {}) };
 }

package/src/changes.js

@@ -0,0 +1,66 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { listRunIds, runsDir } from "./workspace.js";
+
+const PROBLEMS = new Set(["broken", "risk", "warning"]);
+const PLAN_PROBLEMS = new Set(["missing", "missing_params", "wrong_values"]);
+
+const readJson = (file) => readFile(file, "utf8").then(JSON.parse).catch(() => null);
+
+/** The site's newest saved run before this one, with its capture and plan check, or null. */
+export async function previousRun(dataDir, site, before = null) {
+  const ids = (await listRunIds(dataDir, site)).filter((id) => !before || id < before);
+  for (const id of ids.reverse()) {
+    const dir = path.join(runsDir(dataDir, site), id);
+    const capture = await readJson(path.join(dir, "capture.json"));
+    if (capture) return { id, capture, planCheck: await readJson(path.join(dir, "plan-check.json")) };
+  }
+  return null;
+}
+
+/** One entry per problem, keyed so the same problem matches across runs whatever its wording. */
+function findingProblems(findings = []) {
+  const out = new Map();
+  for (const f of findings) {
+    if (!PROBLEMS.has(f.severity)) continue;
+    const k = [f.check, f.platform ?? "", f.event ?? ""].join("|");
+    if (!out.has(k)) out.set(k, { check: f.check, platform: f.platform ?? null, event: f.event ?? null, severity: f.severity, detail: f.detail });
+  }
+  return out;
+}
+
+function planProblems(pc) {
+  const out = new Map();
+  for (const e of pc?.events ?? []) out.set(`${e.platform}|${e.event}`, { platform: e.platform, event: e.event, bucket: e.bucket });
+  return out;
+}
+
+/**
+ * What changed since the previous run of the same site. Compares plan coverage when both runs were
+ * checked against a plan, and the health findings otherwise.
+ * Returns { previous: null } when there is no earlier run, else
+ * { previous, mode: "plan" | "findings", fixed: [...], new: [...] }.
+ */
+export function compareRuns(prev, { findings, planCheck = null }) {
+  if (!prev) return { previous: null };
+  if (planCheck && prev.planCheck) {
+    const before = planProblems(prev.planCheck);
+    const now = planProblems(planCheck);
+    const fixed = [];
+    const added = [];
+    for (const [k, e] of now) {
+      const was = before.get(k)?.bucket;
+      if (e.bucket === "implemented" && PLAN_PROBLEMS.has(was)) fixed.push({ ...e, was });
+      if (PLAN_PROBLEMS.has(e.bucket) && !PLAN_PROBLEMS.has(was)) added.push({ ...e, was: was ?? null });
+    }
+    return { previous: prev.id, mode: "plan", fixed, new: added };
+  }
+  const before = findingProblems(prev.capture?.findings);
+  const now = findingProblems(findings);
+  return {
+    previous: prev.id,
+    mode: "findings",
+    fixed: [...before].filter(([k]) => !now.has(k)).map(([, f]) => f),
+    new: [...now].filter(([k]) => !before.has(k)).map(([, f]) => f),
+  };
+}

package/src/cli.js

@@ -8,11 +8,13 @@ import { helpText } from "./help.js";
 import { replaySavedSite, writeSavedSteps } from "./replay.js";
 import { savePlan } from "./plan.js";
 import { DEFAULT_DATA_DIR } from "./workspace.js";
+import { commandText, intentToArgs, isSentence, needsWhatToTest, translate } from "./ask.js";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
-async function main() {
+async function main(args = process.argv.slice(2)) {
   const { values, positionals } = parseArgs({
+    args,
     allowPositionals: true,
     options: {
       config: { type: "string" },
@@ -49,8 +51,10 @@ async function main() {
       "data-dir": { type: "string" },
       against: { type: "string" },
       from: { type: "string" },
+      topic: { type: "string" },
       format: { type: "string" },
       force: { type: "boolean", default: false },
+      yes: { type: "boolean", short: "y", default: false },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", short: "v", default: false },
     },
@@ -61,6 +65,11 @@ async function main() {
     return;
   }
 
+  if (isSentence(positionals) && !values.help) {
+    const next = await fromSentence(positionals[0], values, args);
+    if (next) await main(next);
+    return;
+  }
   if (command === "mcp" && !values.help) {
     const { startMcp } = await import("./mcp.js");
     await startMcp({ http: values.http, port: values.port ? Number(values.port) : undefined, host: values.host, token: values.token, reportsDir: values.reports, publicUrl: values["public-url"], allowPrivateNetwork: values["allow-private-network"] });
@@ -105,6 +114,7 @@ async function main() {
     if (values.out) throw new Error("plan --out was removed. Plans are saved in aitd/<domain>/plans/<id>/; use --data-dir <dir> to keep them elsewhere.");
     if (values.force) throw new Error("--force was removed. Each plan is saved in a new folder, so nothing is replaced.");
     if (!values.site) throw new Error("plan needs --site <url>: aitd plan --site https://www.example.com");
+    if (values.topic !== undefined) (await import("./discover.js")).checkTopic(values.topic);
     const dataDir = values["data-dir"] ?? DEFAULT_DATA_DIR;
     const { domainOf } = await import("./workspace.js");
     domainOf(values.site); // Checked before the browser starts.
@@ -114,7 +124,7 @@ async function main() {
     const { discoverPlan } = await import("./discover.js");
     const provider = await createProvider({ name: values.provider, model: values.model, baseUrl: values["base-url"] });
     console.log(`Exploring ${values.site} to draft its measurement plan…`);
-    const { plan } = await discoverPlan({ site: values.site, provider, maxSteps, headed: values.headed, allowedHosts: values["allow-host"], log: console.log });
+    const { plan } = await discoverPlan({ site: values.site, topic: values.topic, provider, maxSteps, headed: values.headed, allowedHosts: values["allow-host"], log: console.log });
     const { id, dir } = await savePlan(plan, { dataDir, site: values.site, branding: !values["no-branding"] });
     const custom = plan.events.filter((e) => e.custom).length;
     const rel = path.relative(process.cwd(), dir);
@@ -212,6 +222,67 @@ async function main() {
   }
 }
 
+// aitd "check my GA tags": shows the matching command and runs it once confirmed.
+async function fromSentence(sentence, values, extra) {
+  const { createProvider } = await import("./providers.js");
+  const provider = await createProvider({ name: values.provider, model: values.model, baseUrl: values["base-url"] }).catch((err) => {
+    if (err.code === "NO_API_KEY") return null;
+    throw err;
+  });
+  let { intent } = await translate(sentence, { provider });
+  let r = intentToArgs(intent);
+  if (r.question) {
+    const answer = (await ask(`${r.question} `)).toLowerCase();
+    if (!["plan", "run"].includes(answer)) throw new Error('Answer "plan" or "run", or type the command, e.g. aitd run --help.');
+    r = intentToArgs({ ...intent, action: answer });
+    intent = { ...intent, action: answer };
+  }
+  if (r.unsupported) throw new Error(r.unsupported);
+  let args = r.args;
+  const needsSite = !values.site && !args.includes("--site") && (args[0] === "plan" || !args.includes("--against"));
+  if (needsSite) {
+    const site = await ask("Which site? (e.g. https://www.example.com) ");
+    if (!site) throw new Error("A site is needed. Add it to the sentence or pass --site <url>.");
+    r = intentToArgs({ ...intent, site });
+    args = r.args;
+  }
+  if (needsWhatToTest(args)) args = await whatToTest(args, values);
+  // Options typed next to the sentence (--site, --provider, --headed…) carry over.
+  args = [...args, ...extra.filter((a) => a !== sentence && a !== "-y" && a !== "--yes")];
+  console.log(commandText(args));
+  if (!values.yes) {
+    const answer = (await ask("Run this? (Y/n) ")).toLowerCase();
+    if (answer && !["y", "yes"].includes(answer)) return null;
+  }
+  return args;
+}
+
+// A run needs something to test: suggest the site's latest plan, else ask for a goal.
+async function whatToTest(args, values) {
+  const site = values.site ?? args[args.indexOf("--site") + 1];
+  const { listPlanIds } = await import("./workspace.js");
+  const hasPlan = (await listPlanIds(values["data-dir"] ?? DEFAULT_DATA_DIR, site).catch(() => [])).length > 0;
+  if (hasPlan) {
+    const answer = values.yes ? "" : (await ask("Check against the latest plan? (Y/n) ")).toLowerCase();
+    if (!answer || ["y", "yes"].includes(answer)) return [...args, "--against", "latest"];
+  } else if (values.yes) {
+    throw new Error('Nothing to test yet. Say what to check, e.g. aitd "check my GA tags on the contact form", or draft a plan first.');
+  }
+  const goal = await ask("What should I check, e.g. the contact form? ");
+  if (!goal) throw new Error('Nothing to test. Say what to check, e.g. aitd "check my GA tags on the contact form".');
+  return [...args, "--goal", goal];
+}
+
+async function ask(question) {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
 async function planSheet(action, arg, values) {
   const dataDir = values["data-dir"] ?? DEFAULT_DATA_DIR;
   const shown = (p) => {

package/src/discover.js

@@ -15,6 +15,39 @@ Propose the events this site should track:
 - Suggested user properties (for example customer_type, logged_in, membership_level), with a description and example.
 Only propose what the pages show is possible. Prefer fewer, useful events over many trivial ones.`;
 
+/** Kinds of events a plan can be limited to with --topic: what to explore, what to propose, and which events to keep. */
+const ECOMMERCE = new Set(["view_item_list", "select_item", "view_item", "add_to_cart", "remove_from_cart", "view_cart", "add_to_wishlist", "begin_checkout", "add_shipping_info", "add_payment_info", "purchase", "refund", "view_promotion", "select_promotion"]);
+const FORMS = new Set(["sign_up", "login", "generate_lead"]);
+export const TOPICS = {
+  "custom-events": {
+    explore: "the pages with interactions specific to this site (tools, filters, videos, downloads, configurators, locators)",
+    propose: "custom events for interactions specific to this site. Do not propose GA4 recommended events",
+    keep: (ev) => Boolean(ev.custom),
+  },
+  ecommerce: {
+    explore: "the home page, one listing page, one product page, the cart (add one item first) and the first checkout step",
+    propose: "the GA4 ecommerce events (view_item_list, select_item, view_item, add_to_cart, remove_from_cart, view_cart, begin_checkout, add_shipping_info, add_payment_info, purchase, and promotions) with their items parameters",
+    keep: (ev) => ECOMMERCE.has(ev.name),
+  },
+  forms: {
+    explore: "the sign-up, login, contact and newsletter forms",
+    propose: "form events: sign_up, login, generate_lead, and custom form events (for example form_start, form_submit, form_error, newsletter_signup). Never propose ecommerce events",
+    keep: (ev) => FORMS.has(ev.name) || /form|newsletter|subscribe|signup|sign_up|lead|contact/.test(ev.name),
+  },
+  consent: {
+    explore: "the cookie or consent banner and any privacy settings page. Open the banner's settings before accepting it",
+    propose: "consent events: the banner shown, accepted, rejected and customised (for example consent_banner_view, consent_update), with the chosen categories as parameters. Never propose ecommerce or form events",
+    keep: (ev) => /consent|cookie|privacy|gdpr/.test(ev.name),
+  },
+};
+
+/** Checks a --topic value; undefined means no topic (the whole plan). */
+export function checkTopic(topic) {
+  if (topic === undefined) return undefined;
+  if (!Object.hasOwn(TOPICS, topic)) throw new Error(`Unknown --topic "${topic}". Use one of: ${Object.keys(TOPICS).join(", ")}`);
+  return topic;
+}
+
 const str = { type: "string" };
 const PLAN_SCHEMA = {
   type: "object",
@@ -106,11 +139,14 @@ export function toPlan(site, answer, hits = []) {
 
 /**
  * Lets the AI explore the site (one page per type), then asks it for a measurement plan.
- * @param {{ site: string, provider: any, maxSteps?: number, headed?: boolean, allowedHosts?: string[], viewport?: string, log?: (msg: string) => void }} opts
+ * With `topic`, exploring and the plan are limited to that kind of event (see TOPICS).
+ * @param {{ site: string, topic?: string, provider: any, maxSteps?: number, headed?: boolean, allowedHosts?: string[], viewport?: string, blockPrivate?: boolean, log?: (msg: string) => void }} opts
  */
 export async function discoverPlan(opts) {
   const log = opts.log ?? (() => {});
-  const session = new AuditSession({ viewport: opts.viewport ?? "desktop", site: opts.site, allowedHosts: opts.allowedHosts, headless: !opts.headed });
+  const topic = TOPICS[checkTopic(opts.topic)];
+  const goal = topic ? `${DISCOVER_GOAL}\nThis plan covers only ${opts.topic}: visit just ${topic.explore}, and skip other kinds of page.` : DISCOVER_GOAL;
+  const session = new AuditSession({ viewport: opts.viewport ?? "desktop", site: opts.site, allowedHosts: opts.allowedHosts, headless: !opts.headed, blockPrivate: opts.blockPrivate });
   const snapshots = [];
   let outcome;
   try {
@@ -123,7 +159,7 @@ export async function discoverPlan(opts) {
       snapshots.push(s);
       return s;
     };
-    outcome = await runAgentJourney(session, { id: "discover", goal: DISCOVER_GOAL }, { provider: opts.provider, maxSteps: opts.maxSteps ?? 25, log }).catch((err) => {
+    outcome = await runAgentJourney(session, { id: "discover", goal }, { provider: opts.provider, maxSteps: opts.maxSteps ?? 25, log }).catch((err) => {
       if (err instanceof StepTimeout) return { completed: false, note: err.message };
       throw err;
     });
@@ -135,12 +171,13 @@ export async function discoverPlan(opts) {
   log(`\nExplored ${pages.length} pages${outcome.completed ? "" : ` (${outcome.note})`}. Drafting the plan…`);
   const existing = [...new Set(session.hits.map((h) => `${h.platform}:${h.name}`))];
   const result = await opts.provider.json({
-    system: PLAN_SYSTEM,
+    system: topic ? `${PLAN_SYSTEM}\nThis plan covers only ${opts.topic}. Propose only ${topic.propose}.` : PLAN_SYSTEM,
     texts: [`Site: ${opts.site}`, `Pages visited:\n${JSON.stringify(pages, null, 1)}`, `Tracking hits the site already sends: ${existing.length ? existing.join(", ") : "none"}`],
     schema: PLAN_SCHEMA,
   });
   if (result.error) throw new Error(`The model did not return a plan (${result.error}).`);
   const plan = toPlan(opts.site, result.value, session.hits);
+  if (topic) plan.events = plan.events.filter(topic.keep);
   const coverage = pageTypeCoverage(plan.pages);
   log(`Page types found: ${coverage.found.join(", ") || "none"}`);
   if (coverage.absent.length) log(`Not present on this site: ${coverage.absent.join(", ")}`);

package/src/help.js

@@ -18,13 +18,15 @@ Examples:
   aitd plan --site https://example.com
   aitd run --site https://example.com --against latest
   aitd run --site https://example.com --journey purchase
+  aitd "check my GA tags on example.com"    (shows the command first; -y skips the question)
 
 Run "aitd <command> --help" for that command's options.   -h, --help   -v, --version`;
 
 const RUN = `Usage: aitd run --site <url> (--against <plan> | --journey <id> | --goal "<text>")
 
 Audit what a site actually sends while an AI agent walks its journeys. Needs an AI key
-(${Object.values(PROVIDERS).map((p) => p.env).join(", ")}) unless --no-ai.
+(${Object.values(PROVIDERS).map((p) => p.env).join(", ")}) unless --no-ai. Each run is saved in
+aitd/<domain>/runs/<id>/ and its report says what changed since the site's previous run.
 
 What to test (at least one):
   --against <plan>     Check against a plan: latest, first, a plan ID or a plan file or folder
@@ -62,6 +64,7 @@ Commands:
 
 Options:
   --site <url>         The site (required)
+  --topic <name>       Only plan one kind of event: custom-events, ecommerce, forms or consent
   --headed             Show the browser window
 
 AI:  --provider <name>   --model <id>   (default: whichever API key is set)

package/src/i18n.js

@@ -87,6 +87,12 @@ const en = {
     headerMeta: (journeys, providers) => `${journeys} ${journeys === 1 ? "journey" : "journeys"} · ${providers} ${providers === 1 ? "provider" : "providers"}`,
     checkedAgainst: (id) => `Checked against plan ${id}`,
     planVsSite: "Plan vs. site",
+    changesTitle: "Changed since last run",
+    changesLead: (id, mode) => `Compared with run ${id}, by ${mode === "plan" ? "plan coverage" : "health findings"}`,
+    changesLine: (ch) => ch.fixed.length || ch.new.length ? [ch.fixed.length ? `${ch.fixed.length} ${ch.mode === "plan" ? (ch.fixed.length === 1 ? "event" : "events") : (ch.fixed.length === 1 ? "problem" : "problems")} fixed` : "", ch.new.length ? `${ch.new.length} new ${ch.new.length === 1 ? "problem" : "problems"}` : ""].filter(Boolean).join(", ") : "No changes since the last run",
+    changeFixed: "Fixed",
+    changeNew: "New",
+    noPreviousRun: "This is the first saved run for this site, so there is nothing to compare yet.",
     planVsSiteLead: "Each planned event, and what the site actually sent",
     coverageLine: (c) => `Coverage ${c.implemented} of ${c.checkable}${c.percent === null ? "" : ` (${c.percent}%)`}${c.not_checked ? `, ${c.not_checked} ${c.not_checked === 1 ? "event" : "events"} not checked` : ""}`,
     bucket: { implemented: "Implemented", missing: "Missing", missing_params: "Missing params", wrong_values: "Wrong values", unplanned: "Unplanned", not_checked: "Not checked" },
@@ -240,6 +246,12 @@ const tr = {
     headerMeta: (journeys, providers) => `${journeys} yolculuk · ${providers} sağlayıcı`,
     checkedAgainst: (id) => `${id} planına göre kontrol edildi`,
     planVsSite: "Plan ve site",
+    changesTitle: "Son çalıştırmadan bu yana değişenler",
+    changesLead: (id, mode) => `${id} çalıştırmasıyla ${mode === "plan" ? "plan kapsamına" : "sağlık bulgularına"} göre karşılaştırıldı`,
+    changesLine: (ch) => ch.fixed.length || ch.new.length ? [ch.fixed.length ? `${ch.fixed.length} ${ch.mode === "plan" ? "olay" : "sorun"} düzeldi` : "", ch.new.length ? `${ch.new.length} yeni sorun` : ""].filter(Boolean).join(", ") : "Son çalıştırmadan bu yana değişiklik yok",
+    changeFixed: "Düzeldi",
+    changeNew: "Yeni",
+    noPreviousRun: "Bu site için kayıtlı ilk çalıştırma bu, karşılaştırılacak bir şey henüz yok.",
     planVsSiteLead: "Plandaki her olay ve sitenin gerçekte gönderdiği",
     coverageLine: (c) => `Kapsam ${c.checkable} olaydan ${c.implemented}${c.percent === null ? "" : ` (%${c.percent})`}${c.not_checked ? `, ${c.not_checked} olay kontrol edilmedi` : ""}`,
     bucket: { implemented: "Uygulanmış", missing: "Eksik", missing_params: "Eksik parametre", wrong_values: "Hatalı değer", unplanned: "Planda yok", not_checked: "Kontrol edilmedi" },

package/src/mcp.js

@@ -21,6 +21,9 @@ import { checkRun, groupFindings, summarize } from "./checks.js";
 import { LANGUAGES, messages } from "./i18n.js";
 import { loadConfig, readJson, runAudit, writeReports } from "./audit.js";
 import { DEFAULT_DATA_DIR, resolvePlan } from "./workspace.js";
+import { checkTopic, discoverPlan, TOPICS } from "./discover.js";
+import { createProvider } from "./providers.js";
+import { savePlan } from "./plan.js";
 import { DEFAULT_PROVIDERS, PROVIDERS as TRACKING_PROVIDERS } from "./parsers.js";
 import { expectEvents, filterFindings, JOURNEY_PRESETS, onlyEvents, presetFor, withPresetEvents } from "./journeys.js";
 
@@ -32,6 +35,8 @@ const MIN_TOKEN_LENGTH = 16;
 
 const INSTRUCTIONS = `ai-tag-debugger checks a website's analytics and ad tracking (GA4, Google Ads, Meta Pixel, TikTok Pixel, Consent Mode).
 
+Two kinds of request: a PLAN is what should be tracked, an AUDIT is what the site actually sends. If the user wants to know what to track, which events a site needs, or asks for a tracking or measurement plan, call make_plan (with topic when they only care about one kind of event: ${Object.keys(TOPICS).join(", ")}). If they want to know whether tracking works, what a site sends, or what changed, run an audit. To audit against the plan afterwards, pass against to finish_audit.
+
 Before starting, ask the user which platforms to check and suggest the default (${DEFAULT_PROVIDERS.map((k) => TRACKING_PROVIDERS[k]).join(", ")}); pass their choice as providers.
 
 To audit a journey yourself: call start_audit with the site URL and a journey (a ready-made one: ${Object.keys(JOURNEY_PRESETS).join(", ")}, or the user's own description), then browser_action one step at a time until the journey is done (each result shows the page and the tracking hits that step sent), then finish_audit (with against to check the run against a saved plan) to get the findings and the report. Explain the findings to the user in plain language.
@@ -123,6 +128,7 @@ async function loadAgainst(ref, site, opts) {
  *   blockPrivate: the browser refuses loopback, private and link-local addresses (HTTP servers, by default).
  *   dataDir: where saved plans live (default ./aitd), used by `against`.
  *   reportsUrl: where an HTTP server serves finished reports, if it knows its public URL.
+ *   provider: an AI provider for make_plan (default: the one configured on this computer; tests pass a fake).
  */
 export function buildServer(opts) {
   const server = new McpServer({ name: "ai-tag-debugger", version: VERSION }, { instructions: INSTRUCTIONS });
@@ -298,6 +304,53 @@ export function buildServer(opts) {
     },
   );
 
+  server.registerTool(
+    "make_plan",
+    {
+      title: "Draft a tracking plan",
+      description:
+        "Explores a website and drafts its measurement plan: the events, parameters and user properties it should track. Same as `aitd plan --site`. The plan is saved (use its ID as against in finish_audit to check an audit against it) and the events are returned. Uses the AI provider configured on the computer running this server (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY) and takes a few minutes. To see what the site sends today, run an audit instead.",
+      inputSchema: {
+        site: z.string().describe("The site to plan, e.g. https://www.example.com/"),
+        topic: z.enum(Object.keys(TOPICS)).optional().describe(`Limit the plan to one kind of event: ${Object.keys(TOPICS).join(", ")}. Default: the whole plan.`),
+      },
+    },
+    async ({ site, topic }) => {
+      let url;
+      try {
+        url = new URL(site);
+        if (!["http:", "https:"].includes(url.protocol)) throw new Error();
+      } catch {
+        return fail("site must be an http or https URL.");
+      }
+      if (opts.blockPrivate) {
+        const refused = await navigationError(url.href, { isPrivate: privateHostChecker() });
+        if (refused) return fail(`${refused} Over HTTP, plans are limited to public websites.`);
+      }
+      try {
+        checkTopic(topic);
+        const provider = opts.provider ?? (await createProvider());
+        const { plan } = await discoverPlan({ site: url.href, topic, provider, blockPrivate: opts.blockPrivate });
+        const { id, dir } = await savePlan(plan, { dataDir: opts.dataDir ?? DEFAULT_DATA_DIR, site: url.href });
+        const custom = plan.events.filter((e) => e.custom).length;
+        return text(
+          [
+            `Saved plan ${id}${topic ? ` (${topic} only)` : ""}: ${plan.events.length} events (${custom} custom) and ${plan.user_properties.length} user properties${opts.allowFiles ? ` in ${dir}` : ""}.`,
+            "",
+            ...plan.events.map((e) => `- ${e.platform} ${e.name}${e.custom ? " (custom)" : ""}${e.trigger?.page ? `, on ${e.trigger.page}` : ""}${e.required_params?.length ? `, params: ${e.required_params.join(", ")}` : ""}${e.description ? `: ${e.description}` : ""}`),
+            ...(plan.user_properties.length ? ["", `User properties: ${plan.user_properties.map((p) => p.name).join(", ")}`] : []),
+            "",
+            `Check a site against it with an audit: finish_audit with against "${id}".`,
+          ].join("\n"),
+        );
+      } catch (err) {
+        // The CLI wording (--no-ai) means nothing to a chat app, so say it in this tool's terms.
+        if (err.code === "NO_API_KEY") return fail("No AI provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY) is set on the computer running this server, so it can't draft a plan. Set one and restart the server, or write the plan yourself from what an audit shows and pass it to finish_audit as measurement_plan.");
+        return fail(`Could not draft the plan: ${err.message}`);
+      }
+    },
+  );
+
   if (opts.allowFiles) {
     server.registerTool(
       "run_audit",

package/src/report.js

@@ -149,11 +149,12 @@ const formatPush = (value) => (isConsentEntry(value) ? `gtag(${value.map((v) =>
 const mdText = (v) => String(v ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 const mdCode = (v) => String(v ?? "").replace(/`/g, "'").replace(/\n/g, " ");
 
-export function renderMarkdown({ title, generatedAt, findings, explained, runs, lang = "en", branding = true, against = null, planCheck = null }) {
+export function renderMarkdown({ title, generatedAt, findings, explained, runs, lang = "en", branding = true, against = null, planCheck = null, changes = null }) {
   const m = messages(lang);
   const rows = attachExplanations(findings, explained);
   const counts = summarize(rows);
   const lines = [`# ${mdText(title)}`, "", m.ui.generated(generatedAt), "", ...(against ? [mdText(m.ui.checkedAgainst(against)), ""] : []), `**${m.ui.counts(counts)}**`, ""];
+  if (changes) lines.push(...changesMd(m, changes));
   if (planCheck) lines.push(...planVsSiteMd(m, planCheck));
   const sum = summaryParts(explained?.summary);
   if (sum) {
@@ -619,6 +620,29 @@ const coverageLines = (m, pc) => [
 const pcSort = (pc) => [...pc.events].sort((a, b) => BUCKET_ORDER.indexOf(a.bucket) - BUCKET_ORDER.indexOf(b.bucket) || platformRank(a.platform) - platformRank(b.platform));
 const BUCKET_ORDER = ["missing", "missing_params", "wrong_values", "implemented", "unplanned", "not_checked"];
 
+/** "Changed since last run": one headline, then what was fixed and what is new. */
+const changeLabel = (c) => `${platformLabel(c.platform ?? "")} ${c.event ?? ""}`.trim() || c.check;
+const changeItems = (m, ch) => [
+  ...ch.fixed.map((c) => ({ sev: "ok", tag: m.ui.changeFixed, text: `${changeLabel(c)} (${ch.mode === "findings" ? c.detail : m.ui.bucket[c.was]})` })),
+  ...ch.new.map((c) => ({ sev: "broken", tag: m.ui.changeNew, text: `${changeLabel(c)} (${ch.mode === "findings" ? c.detail : m.ui.bucket[c.bucket]})` })),
+];
+
+function changesMd(m, ch) {
+  const lines = [`## ${m.ui.changesTitle}`, ""];
+  if (!ch.previous) return [...lines, m.ui.noPreviousRun, ""];
+  lines.push(`**${mdText(m.ui.changesLine(ch))}**`, "");
+  const items = changeItems(m, ch);
+  if (items.length) lines.push(...items.map((i) => `- ${i.tag}: ${mdText(i.text)}`), "");
+  return lines;
+}
+
+function changesCard(m, ch) {
+  const head = `<div class="card-h"><div class="card-t">${m.ui.changesTitle}</div>${ch.previous ? `<div class="card-d">${escapeHtml(m.ui.changesLead(ch.previous, ch.mode))}</div>` : ""}</div>`;
+  if (!ch.previous) return `<div class="card" id="changes">${head}<div class="card-c"><p class="muted">${m.ui.noPreviousRun}</p></div></div>`;
+  const items = changeItems(m, ch);
+  return `<div class="card" id="changes">${head}<div class="card-c"><p><strong>${escapeHtml(m.ui.changesLine(ch))}</strong></p>${items.length ? `<ul class="changes">${items.map((i) => `<li>${badge(i.sev, i.tag)} ${escapeHtml(i.text)}</li>`).join("")}</ul>` : ""}</div></div>`;
+}
+
 function planVsSiteMd(m, pc) {
   const [overall, ...perPlatform] = coverageLines(m, pc);
   const lines = [`## ${m.ui.planVsSite}`, "", `**${mdText(overall)}**`, "", ...perPlatform.map((l) => `- ${mdText(l)}`), ...(perPlatform.length ? [""] : [])];
@@ -778,6 +802,7 @@ table.dt a{color:var(--fg)}table.dt a:hover{color:var(--accent-fg)}
 .fsr{position:absolute;opacity:0;width:1px;height:1px;pointer-events:none}
 .sevfilter label{padding:4px 10px;border-radius:4px;font-weight:500;font-size:12px;color:var(--muted);cursor:pointer}
 .filter-host{position:relative}
+.changes{list-style:none;margin:8px 0 0;padding:0;display:grid;gap:6px}
 .flist{list-style:none;margin:0;padding:0;display:grid;gap:8px}
 .finding{--sev:var(--warn-dot);--sev-fg:var(--warn);--sev-bg:var(--warn-bg);background:var(--bg);border:1px solid var(--border);border-left:4px solid var(--sev);border-radius:var(--radius);box-shadow:var(--shadow-sm)}
 .finding.sev-broken{--sev:var(--danger-dot);--sev-fg:var(--danger);--sev-bg:var(--danger-bg)}
@@ -940,7 +965,7 @@ pre{margin:8px 0 0;font-size:12px;line-height:1.5;background:var(--muted-bg);bor
 @media print{.toptabs,.jtabs,.stepnav,.filter>label,.filter>input,.tabs.seg>label,.sevfilter{display:none}.tabpanel,.jpanel,.sdetail,.tabs.seg>.panel{display:block!important}.jpanel{margin-bottom:32px}.sdetail{margin-bottom:16px;break-inside:avoid-page}details>*{display:block}}
 `;
 
-export function renderHtml({ title, generatedAt, findings, explained, runs, plan = null, lang = "en", branding = true, against = null, planCheck = null }) {
+export function renderHtml({ title, generatedAt, findings, explained, runs, plan = null, lang = "en", branding = true, against = null, planCheck = null, changes = null }) {
   const m = messages(lang);
   const rows = attachExplanations(findings, explained);
   const counts = summarize(rows);
@@ -967,7 +992,7 @@ ${navCss(runs)}</style></head><body>
 <nav class="toptabs" aria-label="${m.ui.sections}"><div class="wrap">
 <a href="#overview">${m.ui.tabOverview}</a><a href="#findings">${m.ui.findings} <span class="n">${problems}</span></a><a href="#journeys">${m.ui.tabJourneys} <span class="n">${runs.length}</span></a><a href="#scope">${m.ui.tabScope}</a></div></nav>
 <main class="wrap">
-<section class="tabpanel" id="overview" aria-label="${m.ui.tabOverview}">${planCheck ? planVsSiteCard(m, planCheck) : ""}${overviewTab(m, findings, rows, counts, explained, runs)}</section>
+<section class="tabpanel" id="overview" aria-label="${m.ui.tabOverview}">${changes ? changesCard(m, changes) : ""}${planCheck ? planVsSiteCard(m, planCheck) : ""}${overviewTab(m, findings, rows, counts, explained, runs)}</section>
 <section class="tabpanel" id="findings" aria-label="${m.ui.findings}">${findingsTab(m, runs, rows)}</section>
 <section class="tabpanel" id="journeys" aria-label="${m.ui.tabJourneys}">${journeysTab(m, lang, findings, runs, flagged)}</section>
 <section class="tabpanel" id="scope" aria-label="${m.ui.tabScope}"><div class="stack">${coverageCard(m, plan, runs)}${providersCard(m, runs)}</div></section>