@analitikisler/ai-tag-debugger 0.8.2 → 0.10.0

package/src/discover.js

@@ -0,0 +1,148 @@
+import { AuditSession } from "./browser.js";
+import { runAgentJourney, StepTimeout } from "./agent.js";
+
+/** The goal of the browsing part: one page of each type, nothing submitted. */
+export const DISCOVER_GOAL = `Explore this site to draft its analytics measurement plan. You are not completing a purchase or any other task: visit ONE example of each kind of page that exists here and look at what a visitor can do on it, then call finish with success true.
+Visit, where the site has them (a small site may have only a few; that is fine, don't look for pages that aren't linked): the home page, one category or listing page, one product, item or article page, the cart (add one item first if there is an add-to-cart button), the first checkout step, the search results (search for something the site sells), and the sign-up, login, contact or newsletter forms.
+Rules: never pay, never submit a form with personal details, never open more than one page of the same kind, and accept the cookie banner when it appears. Stop as soon as every kind of page above has been seen once.`;
+
+const PLAN_SYSTEM = `You are a senior digital analytics consultant writing a GA4 measurement plan for a website that may have no tracking yet. You get the pages an explorer visited (their type, address, visible text and interactive elements) and any tracking hits the site already sent.
+
+Propose the events this site should track:
+- Recommended GA4 events where they fit (page_view, view_item_list, view_item, select_item, add_to_cart, view_cart, begin_checkout, purchase, search, sign_up, login, generate_lead, ...), with GA4's recommended parameters.
+- Custom events for interactions specific to this site that a business would want to measure (for example a size guide, a store locator, a video, a configurator, a filter, a download). Name them in snake_case and mark them custom.
+- For each event: what the visitor does, the page type and element that triggers it (quote the element's visible label), its parameters (standard and custom) with one realistic example value taken from the pages when possible, and which parameters are required.
+- 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.`;
+
+const str = { type: "string" };
+const PLAN_SCHEMA = {
+  type: "object",
+  properties: {
+    pages: { type: "array", items: { type: "object", properties: { type: str, url: str }, required: ["type", "url"], additionalProperties: false } },
+    events: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: str,
+          custom: { type: "boolean" },
+          description: str,
+          trigger_page: str,
+          trigger_element: str,
+          parameters: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { name: str, custom: { type: "boolean" }, required: { type: "boolean" }, description: str, example: str },
+              required: ["name", "custom", "required", "description", "example"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["name", "custom", "description", "trigger_page", "trigger_element", "parameters"],
+        additionalProperties: false,
+      },
+    },
+    user_properties: {
+      type: "array",
+      items: { type: "object", properties: { name: str, description: str, example: str }, required: ["name", "description", "example"], additionalProperties: false },
+    },
+  },
+  required: ["pages", "events", "user_properties"],
+  additionalProperties: false,
+};
+
+/** Page types the plan reports on; a site that has fewer of them (a two-page site) is normal, not a failure. */
+export const PAGE_TYPES = ["home", "listing", "detail", "search", "cart", "checkout", "signup", "login", "contact", "newsletter"];
+
+/** Which of PAGE_TYPES the plan's pages cover, and which are absent. Unrecognised type names are ignored. */
+export function pageTypeCoverage(pages = []) {
+  const norm = (t) => String(t ?? "").toLowerCase().replace(/[\s_-]+/g, "");
+  const aliases = { homepage: "home", category: "listing", product: "detail", item: "detail", article: "detail", register: "signup", registration: "signup", basket: "cart", lead: "contact", form: "contact" };
+  const found = new Set(pages.map((p) => aliases[norm(p.type)] ?? norm(p.type)));
+  return { found: PAGE_TYPES.filter((t) => found.has(t)), absent: PAGE_TYPES.filter((t) => !found.has(t)) };
+}
+
+const MAX_PAGES = 15;
+const cut = (s, n) => (s && s.length > n ? `${s.slice(0, n)}…` : s ?? "");
+
+/** One entry per address the explorer saw, keeping the last (fullest) view of each. */
+export function pagesSeen(snapshots) {
+  const byUrl = new Map();
+  for (const s of snapshots) {
+    if (!s?.url || s.url === "about:blank") continue;
+    const key = s.url.split("#")[0];
+    byUrl.delete(key);
+    byUrl.set(key, { url: key, title: s.title, elements: cut(s.elements, 4000), text: cut(s.text, 1500) });
+  }
+  return [...byUrl.values()].slice(-MAX_PAGES);
+}
+
+/** Turns the model's answer into the plan file: the audit's fields plus descriptions, triggers, parameters and user properties. */
+export function toPlan(site, answer, hits = []) {
+  const seen = new Set(hits.filter((h) => h.platform === "ga4").map((h) => h.name));
+  return {
+    site,
+    consent_mode: true,
+    pages: answer.pages ?? [],
+    events: (answer.events ?? []).map((ev) => {
+      const params = ev.parameters ?? [];
+      const required = params.filter((p) => p.required).map((p) => p.name);
+      return {
+        platform: "ga4",
+        name: ev.name,
+        ...(ev.custom ? { custom: true } : {}),
+        description: ev.description,
+        trigger: { page: ev.trigger_page, element: ev.trigger_element },
+        ...(required.length ? { required_params: required } : {}),
+        parameters: Object.fromEntries(params.map((p) => [p.name, { ...(p.custom ? { custom: true } : {}), description: p.description, example: p.example }])),
+        ...(seen.has(ev.name) ? { seen: true } : {}),
+      };
+    }),
+    user_properties: answer.user_properties ?? [],
+  };
+}
+
+/**
+ * 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
+ */
+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 snapshots = [];
+  let outcome;
+  try {
+    await session.start();
+    const startError = await session.act({ action: "goto", url: opts.site, reason: `Open ${opts.site}` });
+    if (startError) throw new Error(`Could not open ${opts.site}: ${startError}`);
+    const snapshot = session.snapshot.bind(session);
+    session.snapshot = async () => {
+      const s = await snapshot();
+      snapshots.push(s);
+      return s;
+    };
+    outcome = await runAgentJourney(session, { id: "discover", goal: DISCOVER_GOAL }, { provider: opts.provider, maxSteps: opts.maxSteps ?? 25, log }).catch((err) => {
+      if (err instanceof StepTimeout) return { completed: false, note: err.message };
+      throw err;
+    });
+  } finally {
+    await session.close();
+  }
+  const pages = pagesSeen(snapshots);
+  if (!pages.length) throw new Error("The explorer saw no pages, so there is nothing to plan from.");
+  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,
+    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);
+  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(", ")}`);
+  return { plan, outcome, coverage };
+}

package/src/help.js

@@ -0,0 +1,104 @@
+import { LANGUAGES } from "./i18n.js";
+import { PROVIDERS } from "./providers.js";
+import { JOURNEY_PRESETS } from "./journeys.js";
+
+const journeys = Object.keys(JOURNEY_PRESETS).join(", ");
+
+const MAIN = `aitd: an open-source AI agent that QA-tests your analytics and ad tracking.
+
+Usage: aitd <command> [options]
+
+Commands:
+  plan     Draft a measurement plan: what should be tracked
+  run      Audit what a site actually sends, and compare it to a plan
+  replay   Re-check saved sites offline, without AI
+  mcp      Start the MCP server for Claude, ChatGPT and other chat apps
+
+Examples:
+  aitd plan --site https://example.com
+  aitd run --site https://example.com --against latest
+  aitd run --site https://example.com --journey purchase
+
+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.
+
+What to test (at least one):
+  --against <plan>     Check against a plan: latest, first, a plan ID or a plan file or folder
+  --journey <id>       A ready-made journey: ${journeys} (repeatable)
+  --goal "<text>"      A journey in plain language (repeatable)
+
+Options:
+  --site <url>         The site to audit
+  --config <file>      Take the site and journeys from a config file
+  --events <names>     Only check these events, e.g. purchase,add_to_cart
+  --lang <code>        Report language: ${Object.keys(LANGUAGES).join(" or ")}
+  --headed             Show the browser window
+  --fail-on <level>    Exit 1 at this level: broken (default), risk, warning, never
+
+AI:  --provider <name>   --model <id>   (default: whichever API key is set)
+
+Advanced:
+  --max-steps <n>   --platforms <list>   --viewport <name>   --data-dir <dir>
+  --scripted   --no-ai   --save-site <dir>   --save-steps <file>   (see the README)`;
+
+const PLAN = `Usage: aitd plan --site <url>
+       aitd plan list --site <url>
+       aitd plan import <file> --site <url>
+       aitd plan export <plan> --site <url>
+
+Draft a measurement plan: what should be tracked. The AI explores one page of each type
+and proposes events, parameters and user properties. Plans are saved in
+aitd/<domain>/plans/<id>/. Needs an AI key (${Object.values(PROVIDERS).map((p) => p.env).join(", ")}).
+
+Commands:
+  (none)               Draft a new plan from the site
+  list                 List the site's plan IDs, oldest first
+  import <file>        Save a plan from a spreadsheet (xlsx or csv) as a new plan
+  export <plan>        Write a plan to a spreadsheet to edit; <plan> is latest, first, an ID or a path
+
+Options:
+  --site <url>         The site (required)
+  --headed             Show the browser window
+
+AI:  --provider <name>   --model <id>   (default: whichever API key is set)
+
+Advanced:
+  --max-steps <n>   --data-dir <dir>   --format <xlsx|csv>   (see the README)`;
+
+const REPLAY = `Usage: aitd replay <dir>... [--update]
+
+Audit sites saved with "aitd run --save-site <dir>" again, offline and without AI, and
+list findings that changed. Exits with code 1 when any did.
+
+Options:
+  --update             Make this replay's findings the expected ones (check the changes first)
+
+Advanced:
+  --out <dir>          Where to write the reports (default: <dir>/last-replay)`;
+
+const MCP = `Usage: aitd mcp [--http] [--port <n>]
+
+Start the MCP server for Claude, ChatGPT, Gemini and other chat apps. It talks over
+stdio unless you pass --http.
+
+Options:
+  --http               Serve over Streamable HTTP, for apps that connect to a URL
+  --port <n>           HTTP port (default 8787)
+
+Advanced:
+  --host <addr>        HTTP host (default 127.0.0.1)
+  --token <secret>     Secret URL path segment, at least 16 characters (default: random)
+  --allow-private-network   Over HTTP, let audits open localhost and private addresses
+  --reports <dir>      Where finished audits write reports (default: ~/ai-tag-debugger-reports)
+  --public-url <url>   The HTTPS address of your tunnel or host, so audits can link to reports`;
+
+const HELP = { run: RUN, plan: PLAN, replay: REPLAY, mcp: MCP };
+
+/** Help text for a command, or the top-level help when the command is unknown or missing. */
+export function helpText(command) {
+  return HELP[command] ?? MAIN;
+}

package/src/i18n.js

@@ -85,6 +85,12 @@ const en = {
     tabScope: "Scope and plan",
     sections: "Report sections",
     headerMeta: (journeys, providers) => `${journeys} ${journeys === 1 ? "journey" : "journeys"} · ${providers} ${providers === 1 ? "provider" : "providers"}`,
+    checkedAgainst: (id) => `Checked against plan ${id}`,
+    planVsSite: "Plan vs. site",
+    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" },
+    bucketCol: "Result",
     summaryLead: "AI summary, most important first",
     noSummary: "Run without --no-ai for an AI summary of the findings.",
     seeAllFindings: "See all findings →",
@@ -121,6 +127,11 @@ const en = {
     missingEventEarly: (name) => `${q(name)} was not seen, but the journey stopped early, so this may not be a tracking bug.`,
     missingParams: (name, params) => `${q(name)} was sent without ${params.map(q).join(", ")}.`,
     duplicate: (name, n) => `${q(name)} was sent ${n} times by one action, which inflates counts and conversions.`,
+    purchaseValueZero: (platform, name, v) => `${platform} ${q(name)} was sent with value ${q(v)}. A purchase worth 0 or less adds no revenue, and ad platforms can't optimize bids on it.`,
+    purchaseValueNaN: (platform, name, v) => `${platform} ${q(name)} was sent with value ${q(v)}, which is not a number, so the revenue is lost. Send a plain number such as 49.90, with no currency sign or thousands separator.`,
+    purchaseCurrency: (platform, name, c) => `${platform} ${q(name)} was sent with currency ${q(c)}, which is not a 3-letter ISO 4217 code in capitals (such as USD, EUR or TRY). Platforms may drop the revenue or convert it wrongly.`,
+    purchaseItemsEmpty: (platform, name) => `${platform} ${q(name)} was sent with no items, so product and item reports get nothing for this order.`,
+    purchaseMismatch: (id, diffs) => `GA4 and Meta reported ${id ? `order ${q(id)}` : "the purchase"} differently: ${diffs.map(([f, g, m]) => `${f} ${q(g)} in GA4 and ${q(m)} in Meta`).join("; ")}. One of the tags reads the wrong data.`,
     serverSide: (platform, server, browser) => `${platform}: ${server.map(q).join(", ")} ${server.length === 1 ? "was" : "were"} sent to a server container on the site's own domain (server-side tagging)${browser.length ? `; ${browser.map(q).join(", ")} went directly from the browser` : ""}. Server-side copies of Meta and TikTok events never pass through the browser, so they can't be seen here.`,
     dedupIdMissing: (platform, name) => `${platform} ${q(name)} was sent from the browser without an event ID, while a server-side setup was seen on this site. If the server also sends this event, ${platform} can't match the two and counts it twice.`,
     consentDefaultMissing: () => "No Google Consent Mode default command (gtag('consent', 'default', ...)) was found in the dataLayer.",
@@ -227,6 +238,12 @@ const tr = {
     tabScope: "Kapsam ve plan",
     sections: "Rapor bölümleri",
     headerMeta: (journeys, providers) => `${journeys} yolculuk · ${providers} sağlayıcı`,
+    checkedAgainst: (id) => `${id} planına göre kontrol edildi`,
+    planVsSite: "Plan ve site",
+    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" },
+    bucketCol: "Sonuç",
     summaryLead: "Yapay zekâ özeti, öncelik sırasıyla",
     noSummary: "Bulguların yapay zekâ özeti için --no-ai olmadan çalıştırın.",
     seeAllFindings: "Tüm bulguları gör →",
@@ -263,6 +280,11 @@ const tr = {
     missingEventEarly: (name) => `${q(name)} görülmedi, ancak yolculuk erken durduğu için bu bir izleme hatası olmayabilir.`,
     missingParams: (name, params) => `${q(name)} olayı ${params.map(q).join(", ")} ${params.length > 1 ? "parametreleri" : "parametresi"} olmadan gönderildi.`,
     duplicate: (name, n) => `${q(name)} tek bir işlemde ${n} kez gönderildi; bu da sayıları ve dönüşümleri şişirir.`,
+    purchaseValueZero: (platform, name, v) => `${platform} ${q(name)} ${q(v)} değeriyle gönderildi. 0 veya daha düşük değerli bir satın alma gelire eklenmez ve reklam platformları teklifleri buna göre optimize edemez.`,
+    purchaseValueNaN: (platform, name, v) => `${platform} ${q(name)} sayı olmayan ${q(v)} değeriyle gönderildi, bu yüzden gelir kayboluyor. Para birimi işareti veya binlik ayırıcı olmadan 49.90 gibi düz bir sayı gönderin.`,
+    purchaseCurrency: (platform, name, c) => `${platform} ${q(name)} ${q(c)} para birimiyle gönderildi; bu, büyük harfli 3 harfli bir ISO 4217 kodu değil (USD, EUR veya TRY gibi). Platformlar geliri atabilir veya yanlış çevirebilir.`,
+    purchaseItemsEmpty: (platform, name) => `${platform} ${q(name)} ürün listesi boş gönderildi, bu yüzden ürün raporları bu siparişten veri alamaz.`,
+    purchaseMismatch: (id, diffs) => `GA4 ve Meta ${id ? `${q(id)} siparişini` : "satın almayı"} farklı bildirdi: ${diffs.map(([f, g, m]) => `${f === "value" ? "değer" : "para birimi"} GA4'te ${q(g)}, Meta'da ${q(m)}`).join("; ")}. Etiketlerden biri yanlış veriyi okuyor.`,
     serverSide: (platform, server, browser) => `${platform}: ${server.map(q).join(", ")} sitenin kendi alan adındaki bir sunucu konteynerine gönderildi (sunucu tarafı etiketleme)${browser.length ? `; ${browser.map(q).join(", ")} doğrudan tarayıcıdan gitti` : ""}. Meta ve TikTok olaylarının sunucu tarafı kopyaları tarayıcıdan geçmez, bu yüzden burada görünmez.`,
     dedupIdMissing: (platform, name) => `${platform} ${q(name)} tarayıcıdan olay kimliği olmadan gönderildi; sitede sunucu tarafı bir kurulum görüldü. Sunucu da bu olayı gönderiyorsa ${platform} ikisini eşleştiremez ve iki kez sayar.`,
     consentDefaultMissing: () => "dataLayer'da Google Consent Mode varsayılan komutu (gtag('consent', 'default', ...)) bulunamadı.",

package/src/journeys.js

@@ -64,11 +64,13 @@ export function presetFor(name) {
  * Adds a journey's preset events to a plan (a copy): events the plan already
  * has are expected on this journey too; missing ones are added for this journey.
  */
-export function withPresetEvents(plan, journeyId, preset) {
+export function withPresetEvents(plan, journeyId, preset, { addMissing = true } = {}) {
   const events = plan.events.map((e) => ({ ...e }));
   for (const pe of preset.events) {
-    const existing = events.find((e) => e.platform === pe.platform && e.name === pe.name);
-    if (!existing) events.push({ ...pe, journeys: [journeyId] });
+    const existing = events.find((e) => String(e.platform).toLowerCase() === pe.platform && e.name === pe.name);
+    if (!existing) {
+      if (addMissing) events.push({ ...pe, journeys: [journeyId] });
+    }
     else if (existing.journeys && !existing.journeys.includes(journeyId)) existing.journeys = [...existing.journeys, journeyId];
   }
   return { ...plan, events };
@@ -80,10 +82,20 @@ export function withPresetEvents(plan, journeyId, preset) {
  *   picks: journey ids from the config or preset names. goals: journeys described in plain language.
  *   events: only check these event names.
  */
-export function planRun({ config = {}, plan, picks = [], goals = [], events = [] }) {
-  // Copied, because the loops below add journeys to events.
-  let runPlan = { ...(plan ?? { events: [] }), events: (plan?.events ?? []).map((e) => ({ ...e })) };
+export function planRun({ config = {}, plan, picks = [], goals = [], events = [], against = false }) {
   const configJourneys = config.journeys ?? [];
+  // --against alone: the plan says what to walk.
+  if (against && !picks.length && !goals.length && !configJourneys.length) {
+    const derived = journeysFromPlan(plan);
+    return { journeys: derived.journeys, plan: onlyEvents(derived.plan, events) };
+  }
+  // --against with --journey or --goal: only plan events expected on those flows are checked;
+  // the rest are expected nowhere, so they are not checked rather than reported missing.
+  const scoped = against && (picks.length || goals.length);
+  let runPlan = {
+    ...(plan ?? { events: [] }),
+    events: (plan?.events ?? []).map((e) => (scoped ? { ...e, journeys: (e.journeys ?? []).filter((j) => picks.includes(j)) } : { ...e })),
+  };
   const journeys = [];
 
   for (const pick of picks) {
@@ -99,13 +111,13 @@ export function planRun({ config = {}, plan, picks = [], goals = [], events = []
     }
     if (journeys.some((j) => j.id === preset.id)) continue;
     journeys.push({ id: preset.id, goal: preset.goal });
-    runPlan = withPresetEvents(runPlan, preset.id, preset);
+    runPlan = withPresetEvents(runPlan, preset.id, preset, { addMissing: !scoped });
   }
 
   goals.forEach((goal, i) => {
     const id = goals.length > 1 ? `custom-${i + 1}` : "custom";
     journeys.push({ id, goal });
-    runPlan = expectEvents(runPlan, id, events);
+    runPlan = expectEvents(runPlan, id, scoped ? [...events, ...eventsNamedIn(goal, runPlan)] : events);
   });
 
   if (!picks.length && !goals.length) journeys.push(...configJourneys);
@@ -140,3 +152,70 @@ export function filterFindings(findings, events = []) {
   const wanted = new Set(events.map((e) => e.toLowerCase()));
   return findings.filter((f) => (f.event ? wanted.has(f.event.toLowerCase()) : f.check !== "unplanned_events"));
 }
+
+const words = (text) => String(text ?? "").toLowerCase().replace(/[_-]+/g, " ");
+
+/** Plan events a plain-language goal mentions, by event name ("add to cart" finds add_to_cart) or "<trigger page> page". */
+export function eventsNamedIn(goal, plan) {
+  const text = words(goal);
+  return plan.events
+    .filter((e) => text.includes(words(e.name)) || (e.trigger?.page && text.includes(`${words(e.trigger.page)} page`)))
+    .map((e) => e.name);
+}
+
+/** Which ready-made journey covers a group of plan events, from the standard GA4 shop and lead events in it. */
+const PRESET_BY_EVENT = [
+  ["purchase", ["purchase", "add_payment_info", "add_shipping_info", "begin_checkout"]],
+  ["add_to_cart", ["add_to_cart", "view_cart"]],
+  ["sign_up", ["sign_up"]],
+  ["lead", ["generate_lead"]],
+  ["search", ["search", "view_search_results"]],
+];
+
+export const MAX_PLAN_JOURNEYS = 6;
+
+const slug = (text) => words(text).trim().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "") || "page";
+
+function goalFor(page, events) {
+  const actions = [...new Set(events.map((e) => e.trigger?.element).filter(Boolean))];
+  const where = page ? `go to a ${page} page` : "browse the site";
+  const doing = actions.length ? ` and use ${actions.map((a) => `"${a}"`).join(", ")}` : "";
+  return `Accept cookies, ${where}${doing}. Never enter real payment details.`;
+}
+
+/**
+ * Journeys for `run --against` used alone: the plan's events grouped by the page they are triggered on
+ * (trigger.page), at most six, each with one goal built from the plan's trigger text (standard shop events
+ * reuse the ready-made journeys) and the group's events expected on it. Returns the journeys and the plan
+ * with each event's "journeys" set.
+ */
+export function journeysFromPlan(plan, max = MAX_PLAN_JOURNEYS) {
+  const groups = new Map();
+  for (const e of plan?.events ?? []) {
+    const page = e.trigger?.page ? String(e.trigger.page).trim() : "";
+    if (!groups.has(page)) groups.set(page, []);
+    groups.get(page).push(e);
+  }
+  // The biggest groups get their own journey; the rest share the last one.
+  let list = [...groups].map(([page, evs]) => ({ page, events: evs })).sort((a, b) => b.events.length - a.events.length);
+  if (list.length > max) {
+    const rest = list.slice(max - 1);
+    list = [...list.slice(0, max - 1), { page: rest.map((g) => g.page).filter(Boolean).join(", "), events: rest.flatMap((g) => g.events), merged: rest }];
+  }
+  const journeys = [];
+  const ids = new Map();
+  for (const group of list) {
+    const names = new Set(group.events.map((e) => e.name));
+    const presetId = PRESET_BY_EVENT.find(([, evs]) => evs.some((n) => names.has(n)))?.[0];
+    const base = presetId && !journeys.some((j) => j.id === presetId) ? presetId : slug(group.page);
+    let id = base;
+    for (let n = 2; journeys.some((j) => j.id === id); n++) id = `${base}_${n}`;
+    const goal = presetId === id ? JOURNEY_PRESETS[presetId].goal : group.merged ? group.merged.map((g) => goalFor(g.page, g.events)).join(" Then ") : goalFor(group.page, group.events);
+    journeys.push({ id, goal, planEvents: group.events.map((e) => e.name) });
+    for (const e of group.events) ids.set(e, id);
+  }
+  return {
+    journeys,
+    plan: { ...plan, events: (plan?.events ?? []).map((e) => ({ ...e, journeys: [ids.get(e)] })) },
+  };
+}

package/src/mcp.js

@@ -20,6 +20,7 @@ import { collect, pageView, SYSTEM_PROMPT } from "./agent.js";
 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 { DEFAULT_PROVIDERS, PROVIDERS as TRACKING_PROVIDERS } from "./parsers.js";
 import { expectEvents, filterFindings, JOURNEY_PRESETS, onlyEvents, presetFor, withPresetEvents } from "./journeys.js";
 
@@ -33,7 +34,7 @@ const INSTRUCTIONS = `ai-tag-debugger checks a website's analytics and ad tracki
 
 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 the measurement plan to get the findings and a full HTML report. Explain the findings to the user in plain language.
+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.
 
 While browsing:
 ${SYSTEM_PROMPT.split("How to work:\n")[1]}`;
@@ -100,10 +101,27 @@ async function readPlan(plan, allowFiles) {
   return readJson(trimmed);
 }
 
+/** finish_audit refuses a bad plan without closing the audit, so the captured run is not lost. */
+const STILL_OPEN = "The audit is still open: call finish_audit again with a corrected plan (or none).";
+
+const AGAINST_DOC = "A saved plan to check against: latest (or last), first, a plan ID such as 2026-10-16_0627, or on a local server a path to a plan file or folder. Plans are the ones saved by `aitd plan --site <url>`.";
+
+/** Finds the saved plan named by `against`. Over HTTP only latest, first and plan IDs are allowed, never paths. */
+async function loadAgainst(ref, site, opts) {
+  if (!opts.allowFiles && !/^(latest|last|first|\d{4}-\d{2}-\d{2}_\d{4}(\d{2})?)$/.test(ref.trim())) {
+    throw new Error("Over HTTP, against takes latest, first or a plan ID, not a path.");
+  }
+  const found = await resolvePlan(ref, { dataDir: opts.dataDir ?? DEFAULT_DATA_DIR, site });
+  const plan = await readJson(found.file);
+  if (!Array.isArray(plan?.events)) throw new Error(`${found.file} is not a plan: it needs an "events" list.`);
+  return { found, plan };
+}
+
 /**
- * @param {{ allowFiles: boolean, blockPrivate?: boolean, reportsDir: string, reportsUrl?: string }} opts
+ * @param {{ allowFiles: boolean, blockPrivate?: boolean, reportsDir: string, reportsUrl?: string, dataDir?: string }} opts
  *   allowFiles: local (stdio) servers may read config and plan files; HTTP servers may not.
  *   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.
  */
 export function buildServer(opts) {
@@ -214,7 +232,7 @@ export function buildServer(opts) {
     {
       title: "Finish and check the audit",
       description:
-        "Closes the browser, checks every captured hit against the measurement plan (missing events, missing parameters, duplicates, hits before consent, Consent Mode defaults, emails sent in plain text, unplanned events) and writes a full HTML report with the event timeline. Returns the findings.",
+        "Closes the browser, checks every captured hit against the plan (missing events, missing parameters, duplicates, hits before consent, Consent Mode defaults, emails sent in plain text, unplanned events) and writes the report with the event timeline. Returns the findings. The plan is what should be tracked: pass a saved one with against, or write one inline with measurement_plan.",
       inputSchema: {
         audit_id: z.string(),
         completed: z.boolean().describe("Whether the journey reached its goal."),
@@ -223,21 +241,28 @@ export function buildServer(opts) {
           .string()
           .optional()
           .describe(
-            'The measurement plan as JSON text, e.g. {"consent_mode": true, "events": [{"platform": "ga4", "name": "purchase", "required_params": ["transaction_id", "value", "currency"]}]}. On a local server this can also be a file path. Without a plan, a ready-made journey checks its own events; otherwise only consent, duplicate and personal data checks run.',
+            'The plan (what should be tracked) as JSON text, e.g. {"consent_mode": true, "events": [{"platform": "ga4", "name": "purchase", "required_params": ["transaction_id", "value", "currency"]}]}. On a local server this can also be a file path. Without a plan, a ready-made journey checks its own events; otherwise only consent, duplicate and personal data checks run.',
           ),
+        against: z.string().optional().describe(`${AGAINST_DOC} The site comes from this audit. Use either against or measurement_plan, not both.`),
         events: z.array(z.string()).optional().describe("Only check these events, e.g. [\"purchase\", \"add_to_cart\"]. On your own journey, these events are also expected to fire."),
         language: z.enum(Object.keys(LANGUAGES)).optional().describe("Report language. Default en."),
         branding: z.boolean().optional().describe("Set false to leave the Analitik İşler logo and credit line out of the report."),
       },
     },
-    async ({ audit_id, completed, note, measurement_plan, events = [], language, branding }) => {
+    async ({ audit_id, completed, note, measurement_plan, against, events = [], language, branding }) => {
       const audit = getAudit(audit_id);
+      if (against && measurement_plan) return fail(`Use either against or measurement_plan, not both. ${STILL_OPEN}`);
       let plan;
+      let againstPlan = null;
       try {
-        plan = await readPlan(measurement_plan, opts.allowFiles);
+        if (against) {
+          const loaded = await loadAgainst(against, audit.site, opts);
+          plan = loaded.plan;
+          againstPlan = { ...loaded.found, label: loaded.found.id ?? path.relative(process.cwd(), loaded.found.file) };
+        } else plan = await readPlan(measurement_plan, opts.allowFiles);
         if (!Array.isArray(plan.events)) throw new Error('The plan needs an "events" list.');
       } catch (err) {
-        return fail(`Could not read the measurement plan: ${err.message}`);
+        return fail(`Could not read the plan: ${err.message} ${STILL_OPEN}`);
       }
       if (audit.preset) plan = withPresetEvents(plan, audit.journey, audit.preset);
       else plan = expectEvents(plan, audit.journey, events);
@@ -251,10 +276,11 @@ export function buildServer(opts) {
       const grouped = groupFindings(findings);
       const counts = summarize(grouped);
       const outDir = path.join(opts.reportsDir, `${new Date().toISOString().replace(/[:.]/g, "-")}-${audit.journey}`);
-      const reportPath = await writeReports({ outDir, config: { site: audit.site }, plan, runs: [run], findings, explained: null, lang, branding: branding !== false });
+      const reportPath = await writeReports({ outDir, config: { site: audit.site }, plan, runs: [run], findings, explained: null, lang, against: againstPlan, branding: branding !== false });
       const m = messages(lang);
       const lines = [
         m.ui.counts(counts),
+        ...(againstPlan ? [m.ui.checkedAgainst(againstPlan.label)] : []),
         "",
         ...grouped.filter((f) => f.severity !== "ok").map((f) => `- ${m.severity[f.severity]}: ${f.detail}${f.evidence ? ` (captured: ${f.evidence})` : ""} [${f.where.map((w) => m.ui.whereStep(w.journey, w.viewport, w.step)).join("; ")}]`),
         "",
@@ -278,9 +304,10 @@ export function buildServer(opts) {
       {
         title: "Run a configured audit",
         description:
-          "Runs every journey in a ai-tag-debugger config file. With scripted true, it replays each journey's fixed steps and needs no API key. Otherwise the journeys are browsed by the AI provider configured on this computer (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY). Writes the reports and returns the findings.",
+          "Runs every journey in a ai-tag-debugger config file and writes the report. With against, the run is checked against a saved plan and, if the config has no journeys, walks the journeys derived from that plan. With scripted true, it replays each journey's fixed steps and needs no API key. Otherwise the journeys are browsed by the AI provider configured on this computer (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY). Returns the findings.",
         inputSchema: {
           config: z.string().describe("Path to the config file, e.g. ai-tag-debugger.config.json"),
+          against: z.string().optional().describe(`${AGAINST_DOC} The site comes from the config.`),
           scripted: z.boolean().optional().describe("Replay fixed steps instead of browsing with an AI model. Default true."),
           language: z.enum(Object.keys(LANGUAGES)).optional(),
           branding: z.boolean().optional().describe("Set false to leave the Analitik İşler logo and credit line out of the report."),
@@ -290,12 +317,26 @@ export function buildServer(opts) {
             .describe(`Tracking providers to check. Default ${DEFAULT_PROVIDERS.join(", ")}. Requests to the others are still answered locally, but they are only counted, not shown or checked.`),
         },
       },
-      async ({ config: configFile, scripted, language, branding, providers }) => {
+      async ({ config: configFile, against, scripted, language, branding, providers }) => {
         const loaded = await loadConfig(configFile);
+        let againstPlan = null;
+        if (against) {
+          try {
+            const found = await loadAgainst(against, loaded.config.site, opts);
+            if (!loaded.config.site) {
+              if (!found.plan.site) throw new Error(`${found.found.file} has no "site" and the config has none either.`);
+              loaded.config = { ...loaded.config, site: found.plan.site };
+            }
+            loaded.plan = found.plan;
+            againstPlan = found.found;
+          } catch (err) {
+            return fail(`Could not read the plan: ${err.message}`);
+          }
+        }
         const replay = scripted !== false;
         let result;
         try {
-          result = await runAudit({ ...loaded, scripted: replay, ai: !replay, lang: language, branding, providers, outDir: path.join(opts.reportsDir, new Date().toISOString().replace(/[:.]/g, "-")) });
+          result = await runAudit({ ...loaded, scripted: replay, ai: !replay, lang: language, branding, providers, against: againstPlan, outDir: path.join(opts.reportsDir, new Date().toISOString().replace(/[:.]/g, "-")) });
         } catch (err) {
           // The CLI wording (--scripted --no-ai) means nothing to a chat app, so say it in this tool's terms.
           if (err.code !== "NO_API_KEY") throw err;