@analitikisler/ai-tag-debugger 0.9.0 → 0.11.0

package/src/i18n.js

@@ -85,6 +85,18 @@ 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",
+    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" },
+    bucketCol: "Result",
     summaryLead: "AI summary, most important first",
     noSummary: "Run without --no-ai for an AI summary of the findings.",
     seeAllFindings: "See all findings →",
@@ -232,6 +244,18 @@ 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",
+    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" },
+    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 →",

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,10 @@ 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 { 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";
 
@@ -31,9 +35,11 @@ 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 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,11 +106,29 @@ 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.
+ *   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 });
@@ -214,7 +238,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 +247,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 +282,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("; ")}]`),
         "",
@@ -272,15 +304,63 @@ 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",
       {
         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 +370,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;

package/src/plan-html.js

@@ -0,0 +1,76 @@
+import { CSS, VERSION, escapeHtml, logo, platformLabel } from "./report.js";
+import { LOGOS } from "./brand.js";
+
+const e = escapeHtml;
+const text = (v) => (v === undefined || v === null || v === "" ? `<span class="muted">–</span>` : e(v));
+
+const PLAN_CSS = `
+.pl-event{padding:16px 20px}
+.pl-event+.pl-event{border-top:1px solid var(--border)}
+.pl-head{display:flex;flex-wrap:wrap;align-items:center;gap:8px}
+.pl-head code{font-size:14px}
+.pl-desc{margin:6px 0 10px}
+.pl-trigger{font-size:12px;color:var(--muted);margin-bottom:10px}
+.pl-trigger b{font-weight:500;color:var(--fg)}
+.flag{display:inline-flex;align-items:center;font:500 12px/1 var(--font-sans);padding:4px 8px;border-radius:4px;background:var(--muted-bg);color:var(--muted)}
+.flag.on{background:var(--accent-bg);color:var(--accent-fg)}
+.flag.req{background:var(--warn-bg);color:var(--warn)}
+table.dt td,table.dt th{vertical-align:top}
+`;
+
+const flag = (label, cls = "") => `<span class="flag ${cls}">${e(label)}</span>`;
+
+function paramsTable(event) {
+  const params = Object.entries(event.parameters ?? {});
+  if (!params.length) return `<p class="muted xs">No parameters.</p>`;
+  const required = new Set(event.required_params ?? []);
+  const rows = params
+    .map(([name, p]) => `<tr><td><code>${e(name)}</code>${p?.custom ? ` ${flag("custom")}` : ""}</td><td>${required.has(name) ? flag("required", "req") : `<span class="muted">optional</span>`}</td><td class="mono">${text(p?.example)}</td><td>${text(p?.description)}</td></tr>`)
+    .join("");
+  return `<div class="tscroll"><table class="dt"><thead><tr><th>Parameter</th><th>Required</th><th>Example</th><th>Description</th></tr></thead><tbody>${rows}</tbody></table></div>`;
+}
+
+function eventCard(event) {
+  const trigger = event.trigger ?? {};
+  return `<div class="pl-event">
+<div class="pl-head"><span class="ptag">${e(platformLabel(event.platform ?? "ga4"))}</span><code>${e(event.name)}</code>${flag(event.custom ? "custom event" : "standard event", event.custom ? "on" : "")}</div>
+<p class="pl-desc">${text(event.description)}</p>
+<p class="pl-trigger"><b>Trigger</b> · page: ${text(trigger.page)} · element: ${text(trigger.element)}</p>
+${paramsTable(event)}
+</div>`;
+}
+
+function userPropertiesCard(props) {
+  const body = props.length
+    ? `<div class="tscroll"><table class="dt"><thead><tr><th>Name</th><th>Example</th><th>Description</th></tr></thead><tbody>${props
+        .map((p) => (typeof p === "string" ? { name: p } : p))
+        .map((p) => `<tr><td><code>${e(p.name)}</code></td><td class="mono">${text(p.example)}</td><td>${text(p.description)}</td></tr>`)
+        .join("")}</tbody></table></div>`
+    : `<p class="muted xs">No user properties.</p>`;
+  return `<section class="card"><div class="card-h"><div class="card-t">User properties</div></div><div class="card-c">${body}</div></section>`;
+}
+
+/** A single self-contained, readable page for a measurement plan. Respects branding false like the report. */
+export function renderPlanHtml(plan, { id = "", generatedAt = "", branding = true } = {}) {
+  const events = plan.events ?? [];
+  const custom = events.filter((ev) => ev.custom).length;
+  const title = `Measurement plan${plan.site ? `: ${plan.site}` : ""}`;
+  const meta = [id && `Plan ${id}`, generatedAt, `${events.length} events (${custom} custom)`, `ai-tag-debugger ${VERSION}`].filter(Boolean).join(" · ");
+  const consent = plan.consent_mode ? flag("Consent mode on", "on") : flag("Consent mode off");
+  const footer = branding
+    ? `<div class="wrap"><a href="https://analitikisler.com" class="logo-link" aria-label="analitikisler.com" rel="noopener noreferrer">${logo("stacked", "Analitik İşler", 56, "logo-s")}</a><div><div class="f-links"><a href="https://analitikisler.com" rel="noopener noreferrer">analitikisler.com</a><a href="https://github.com/analitikisler/ai-tag-debugger" rel="noopener noreferrer">GitHub</a></div></div><div class="f-meta">v${VERSION}</div></div>`
+    : `<div class="wrap plain"><div class="f-meta">AI Tag Debugger</div><div class="f-meta">v${VERSION}</div></div>`;
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${e(title)}</title><link rel="icon" type="image/png" href="${LOGOS.favicon}">
+<style>${CSS}${PLAN_CSS}</style></head><body>
+<div class="topbar"><div class="wrap"><span class="product-logo">${logo("atd-lockup", "AI Tag Debugger", 26, "logo-atd")}</span>${branding ? `<a href="https://analitikisler.com" class="byline" rel="noopener noreferrer"><span>by</span>${logo("horizontal", "Analitik İşler", 18, "logo-h")}</a>` : ""}</div></div>
+<header class="wrap title"><div class="eyebrow">Measurement plan</div><h1>${e(title)}</h1><div class="meta">${e(meta)}</div></header>
+<main class="wrap" style="padding-top:24px;padding-bottom:64px"><div class="stack">
+<div>${consent}</div>
+<section class="card"><div class="card-h"><div class="card-t">Events</div><div class="card-d">What should be tracked, where it fires and which parameters it carries.</div></div><div class="card-c tight">${events.length ? events.map(eventCard).join("") : `<p class="muted xs" style="padding:12px">No events.</p>`}</div></section>
+${userPropertiesCard(plan.user_properties ?? [])}
+</div></main>
+<footer class="footer">${footer}</footer>
+</body></html>`;
+}

package/src/plan.js

@@ -0,0 +1,14 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { renderPlanHtml } from "./plan-html.js";
+import { PLAN_FILE, PLAN_HTML_FILE, newPlanDir } from "./workspace.js";
+
+/** Saves a plan (measurement-plan.json and plan.html) in a new aitd/<domain>/plans/<id>/ folder and returns where. */
+export async function savePlan(plan, { dataDir, site, now, branding = true } = {}) {
+  const { id, dir } = await newPlanDir(dataDir, site, now);
+  await mkdir(dir, { recursive: true });
+  const file = path.join(dir, PLAN_FILE);
+  await writeFile(file, `${JSON.stringify(plan, null, 2)}\n`);
+  await writeFile(path.join(dir, PLAN_HTML_FILE), renderPlanHtml(plan, { id, generatedAt: (now ?? new Date()).toISOString().slice(0, 16).replace("T", " "), branding }));
+  return { id, dir, file };
+}

package/src/providers.js

@@ -28,7 +28,7 @@ export function resolveProviderName(name, env = process.env) {
   return "anthropic";
 }
 
-const NO_API_KEY = `No AI provider key found. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY (or OPENAI_COMPATIBLE_BASE_URL for an OpenAI-compatible API), or pick one with --provider. To run without any AI model, replay the fixed steps with --scripted --no-ai.`;
+const NO_API_KEY = `No AI provider key found. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY (or OPENAI_COMPATIBLE_BASE_URL for an OpenAI-compatible API), or pick one with --provider. To run without any AI model, replay saved steps with --no-ai.`;
 
 function hasApiKey(env) {
   return Boolean(env.OPENAI_COMPATIBLE_BASE_URL || env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN || env.OPENAI_API_KEY || env.GEMINI_API_KEY || env.GOOGLE_API_KEY);

package/src/report.js

@@ -6,7 +6,7 @@ import { decodeGa4Item, isEventParam, paramTip } from "./glossary.js";
 import { LOGOS } from "./brand.js";
 import { readFileSync } from "node:fs";
 
-const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
 const EXPLAIN_SYSTEM = `You are a senior digital analytics consultant reviewing an automated tracking audit. You receive findings from deterministic checks, the measurement plan, the hits captured on each step of each journey, and optionally a Google Tag Manager container export.
 
@@ -120,7 +120,7 @@ export async function explainFindings({ findings, plan, runs, gtmContainer, prov
   }
 }
 
-const escapeHtml = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export const escapeHtml = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 
 function attachExplanations(findings, explained) {
   const byIndex = new Map((explained?.explanations ?? []).map((e) => [e.finding, e]));
@@ -149,11 +149,13 @@ 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 }) {
+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), "", `**${m.ui.counts(counts)}**`, ""];
+  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) {
     lines.push(`## ${m.ui.summary}`, "", sum.text ? mdText(sum.text) : `**${mdText(sum.headline)}**`, "");
@@ -193,7 +195,7 @@ export function renderMarkdown({ title, generatedAt, findings, explained, runs,
 }
 
 const PLATFORM_ORDER = ["ga4", "google_ads", "meta", "tiktok", "x", "pinterest", "snapchat", "klaviyo", "hotjar"];
-const platformLabel = (p) => PROVIDERS[p] ?? String(p).replace(/[_-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+export const platformLabel = (p) => PROVIDERS[p] ?? String(p).replace(/[_-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 const platformRank = (p) => (PLATFORM_ORDER.includes(p) ? PLATFORM_ORDER.indexOf(p) : PLATFORM_ORDER.length);
 
 // Pixel event names and their GA4 / dataLayer counterparts, so a Meta or TikTok hit can be shown next to the push behind it.
@@ -455,7 +457,7 @@ const sevIcon = (sev) => ICON[sev === "broken" ? "broken" : sev === "info" ? "in
 const sec = (name, label) => `<div class="sec-h">${ic(ICON[name], 14)}<span>${label}</span></div>`;
 const badge = (sev, text) => `<span class="badge ${sev}">${escapeHtml(text)}</span>`;
 /** A logo with its light and dark versions, switched by the viewer's color scheme. */
-const logo = (key, alt, height, cls) => `<picture class="${cls}"><source media="(prefers-color-scheme: dark)" srcset="${LOGOS[`${key}-dark`]}"><img src="${LOGOS[`${key}-light`]}" alt="${alt}" height="${height}"></picture>`;
+export const logo = (key, alt, height, cls) => `<picture class="${cls}"><source media="(prefers-color-scheme: dark)" srcset="${LOGOS[`${key}-dark`]}"><img src="${LOGOS[`${key}-light`]}" alt="${alt}" height="${height}"></picture>`;
 
 /** The journey and step a finding's place points at. Steps are named by label; when labels repeat, prefer the step where the finding's event fired. */
 function whereTarget(runs, w, f) {
@@ -610,6 +612,52 @@ ${provs.length ? `<div class="card"><div class="card-h"><div class="card-t">${m.
 }
 
 /** Each planned event × each journey: sent, not sent, or not expected there (or its provider not checked). */
+const BUCKET_SEV = { implemented: "ok", missing: "broken", missing_params: "broken", wrong_values: "warning", unplanned: "info", not_checked: "muted" };
+const coverageLines = (m, pc) => [
+  m.ui.coverageLine(pc.coverage),
+  ...sortPlatforms(Object.keys(pc.coverage.platforms)).map((p) => `${platformLabel(p)}: ${m.ui.coverageLine(pc.coverage.platforms[p])}`),
+];
+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 ? [""] : [])];
+  lines.push(`| ${m.ui.event} | ${m.ui.bucketCol} | |`, "|---|---|---|");
+  for (const e of pcSort(pc)) lines.push(`| ${mdText(platformLabel(e.platform))} \`${mdCode(e.event)}\` | ${m.ui.bucket[e.bucket]} | ${mdText((e.details ?? []).join(" ")).replace(/\|/g, "\\|")} |`);
+  lines.push("");
+  return lines;
+}
+
+function planVsSiteCard(m, pc) {
+  const [overall, ...perPlatform] = coverageLines(m, pc);
+  const rows = pcSort(pc).map((e) => `<tr><td><span class="ptag p-${safeKey(e.platform)}">${escapeHtml(platformLabel(e.platform))}</span> <code>${escapeHtml(e.event)}</code></td><td>${badge(BUCKET_SEV[e.bucket], m.ui.bucket[e.bucket])}</td><td class="muted xs">${(e.details ?? []).map(detailHtml).join("<br>")}</td></tr>`).join("");
+  return `<div class="card" id="plan-vs-site"><div class="card-h"><div class="card-t">${m.ui.planVsSite}</div><div class="card-d">${m.ui.planVsSiteLead}</div></div><div class="card-c"><p><strong>${escapeHtml(overall)}</strong></p>${perPlatform.length ? `<p class="muted xs">${perPlatform.map(escapeHtml).join("<br>")}</p>` : ""}<div class="tscroll"><table class="dt"><thead><tr><th>${m.ui.event}</th><th>${m.ui.bucketCol}</th><th></th></tr></thead><tbody>${rows}</tbody></table></div></div></div>`;
+}
+
 function coverageCard(m, plan, runs) {
   const head = `<div class="card-h"><div class="card-t">${m.ui.planCoverage}</div><div class="card-d">${m.ui.planCoverageLead}</div></div>`;
   if (!plan?.events?.length || !runs.length) return `<div class="card">${head}<div class="card-c"><p class="muted">${m.ui.noPlan}</p></div></div>`;
@@ -679,7 +727,7 @@ function navCss(runs) {
   return out.join("\n");
 }
 
-const CSS = `
+export const CSS = `
 :root{
 --bg:#FFFFFF;--page:#F7F9FC;--fg:#0A0E1A;--muted:#5A6480;--muted-bg:#F1F4F9;--border:#E3E7EF;--input:#E3E7EF;
 --accent:#4F8EF7;--accent-fg:#2F6FDB;--accent-bg:#EBF1FE;--orange:#FF6D33;
@@ -754,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)}
@@ -916,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 }) {
+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);
@@ -938,12 +987,12 @@ ${navCss(runs)}</style></head><body>
 <header class="wrap title">
 <div class="eyebrow">${m.ui.eyebrow}</div>
 <h1>${escapeHtml(title)}</h1>
-<div class="meta">${escapeHtml(generatedAt)} · ${escapeHtml(m.ui.headerMeta(runs.length, checkedProviders(runs).length))} · ai-tag-debugger ${VERSION}</div>
+<div class="meta">${escapeHtml(generatedAt)} · ${escapeHtml(m.ui.headerMeta(runs.length, checkedProviders(runs).length))} · ai-tag-debugger ${VERSION}</div>${against ? `\n<div class="meta">${escapeHtml(m.ui.checkedAgainst(against))}</div>` : ""}
 </header>
 <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}">${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>