@analitikisler/ai-tag-debugger 0.9.0 → 0.10.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
   "mcpName": "io.github.analitikisler/ai-tag-debugger",
-  "version": "0.9.0",
+  "version": "0.10.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": {
@@ -18,7 +18,7 @@
     "setup": "node scripts/setup.js",
     "test": "node --test test/*.test.js",
     "demo:serve": "node examples/serve.js",
-    "demo": "node src/cli.js run --config examples/demo.config.json --scripted --no-ai --out reports/demo"
+    "demo": "node src/cli.js run --config examples/demo.config.json --scripted --no-ai"
   },
   "engines": {
     "node": ">=20"
@@ -57,5 +57,8 @@
     "openai": "^7.30.1",
     "playwright": "1.56.1",
     "zod": "^4.6.5"
+  },
+  "optionalDependencies": {
+    "fflate": "^0.8.3"
   }
 }

package/src/agent.js

@@ -95,7 +95,7 @@ const TIMEOUTS = { model: 180_000, action: 120_000, page: 60_000 };
 
 const LAST_STEP_WAIT_MS = 3000;
 
-class StepTimeout extends Error {}
+export class StepTimeout extends Error {}
 
 /** The promise's value, or a StepTimeout with this message once ms have passed. */
 function withTimeout(promise, ms, message) {

package/src/audit.js

@@ -1,14 +1,15 @@
 // 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 { readFile, mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { failedRun, runJourney } from "./agent.js";
 import { VIEWPORTS } from "./browser.js";
-import { checkRun, groupFindings, summarize } from "./checks.js";
+import { checkRun, groupFindings, planCheck, summarize } from "./checks.js";
 import { explainFindings, renderCsv, renderHtml, renderMarkdown } from "./report.js";
 import { LANGUAGES, messages } from "./i18n.js";
 import { createProvider } from "./providers.js";
-import { filterFindings, planRun } from "./journeys.js";
+import { filterFindings, JOURNEY_PRESETS, planRun } from "./journeys.js";
 import { resolveProviders } from "./parsers.js";
 import { SAVED_SITE_FILE, writeSavedSite } from "./replay.js";
 
@@ -32,30 +33,33 @@ export async function loadConfig(configFile) {
   return { config, plan, gtmContainer };
 }
 
-export const defaultOutDir = () => path.resolve("reports", new Date().toISOString().replace(/[:.]/g, "-"));
 
-/** Writes report.md, report.html, timeline.csv and capture.json. */
-export async function writeReports({ outDir, config, plan, runs, findings, explained, lang, branding = config.branding !== false }) {
+/** 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 }) {
   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 report = { title, generatedAt, findings, explained, runs, plan, lang, branding };
+  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 };
   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));
-  await writeFile(path.join(outDir, "capture.json"), JSON.stringify({ config: { ...config, plan }, runs, findings, explained }, null, 2));
+  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));
   return path.join(outDir, "report.html");
 }
 
 /**
  * @param {{ config: any, plan?: any, gtmContainer?: any, journeys?: string[], goals?: string[], events?: string[], viewports?: string[],
  *   scripted?: boolean, ai?: boolean, provider?: string, model?: string, baseUrl?: string, maxSteps?: number, lang?: string, headed?: boolean,
- *   outDir?: string, branding?: boolean, providers?: string[], saveSite?: string, replaySite?: string, log?: (m: string) => void }} opts
+ *   outDir?: string, dataDir?: string, branding?: boolean, providers?: string[], saveSite?: string, replaySite?: string, log?: (m: string) => void }} opts
  *   journeys: config journey ids or ready-made journeys (purchase, add_to_cart, sign_up, lead, search).
  *   goals: extra journeys described in plain language. events: only check these events.
  *   providers: tracking providers to check (default: config "providers", else GA4, Google Ads, Meta, TikTok).
  *   saveSite: record the site's responses and the steps taken into this folder, for replaySite (see replay.js).
  *   replaySite: answer every request from a folder saved with saveSite, without the network.
+ *   against: { id, file } of the plan given with --against; opts.plan is then that plan. Used alone, the
+ *   journeys come from the plan; with journeys or goals, only the plan events expected on them are checked.
  */
 export async function runAudit(opts) {
   const { gtmContainer } = opts;
@@ -68,19 +72,29 @@ export async function runAudit(opts) {
   const useAi = opts.ai !== false;
   if (!useAi && !opts.scripted) throw new Error("Without an AI model, journeys must be replayed from their fixed steps (scripted).");
 
-  const { journeys, plan } = planRun({ config, plan: opts.plan, picks: opts.journeys, goals: opts.goals, events });
+  const against = opts.against ? { ...opts.against, label: opts.against.id ?? path.relative(process.cwd(), opts.against.file) } : null;
+  const { journeys, plan } = planRun({ config, plan: opts.plan, picks: opts.journeys, goals: opts.goals, events, against: Boolean(against) });
   config = { ...config, providers: resolveProviders(opts.providers ?? config.providers, plan) };
   const viewports = opts.viewports?.length ? opts.viewports : config.viewports ?? ["desktop"];
   const allowed = Object.keys(VIEWPORTS).join(", ");
   if (!Array.isArray(viewports)) throw new Error(`"viewports" must be a list, e.g. ["desktop", "mobile"]. Allowed values: ${allowed}.`);
   const unknown = viewports.filter((v) => !Object.hasOwn(VIEWPORTS, v));
   if (unknown.length) throw new Error(`Unknown viewport ${unknown.map((v) => `"${v}"`).join(", ")}. Use: ${allowed}.`);
-  if (!journeys.length) throw new Error("No journeys to run. Pick one with --journey (e.g. purchase) or describe one with --goal.");
+  if (!journeys.length) throw new Error(`No journeys to run. A run needs one of:\n  --journey <name>   one of: ${Object.keys(JOURNEY_PRESETS).join(", ")} (or a journey id from your config)\n  --goal "<text>"    describe what to do in your own words\n  --config <file>    a config file with "journeys"\nNot sure what to test? "aitd plan --site ${config.site}" drafts a measurement plan.`);
   if (opts.scripted) {
     const unscripted = journeys.filter((j) => !j.steps?.length && !j.incomplete).map((j) => j.id);
     if (unscripted.length) throw new Error(`Journeys without fixed steps can't be replayed with --scripted: ${unscripted.join(", ")}.`);
   }
 
+  if (against) {
+    const notChecked = plan.events.filter((e) => Array.isArray(e.journeys) && !e.journeys.some((j) => journeys.some((jj) => jj.id === j))).length;
+    log(`Checking against plan ${against.label}: ${journeys.length} ${journeys.length === 1 ? "journey" : "journeys"}${notChecked ? `, ${notChecked} planned ${notChecked === 1 ? "event" : "events"} not checked in this run` : ""}`);
+    for (const j of journeys) {
+      const expected = plan.events.filter((e) => !e.journeys || e.journeys.includes(j.id)).map((e) => e.name);
+      log(`  - ${j.id}: ${j.goal ?? "fixed steps"}${expected.length ? ` [${[...new Set(expected)].join(", ")}]` : ""}`);
+    }
+  }
+
   const provider = useAi ? await createProvider({ name: opts.provider ?? config.provider, model: opts.model ?? config.model, baseUrl: opts.baseUrl ?? config.base_url }) : null;
   if (provider) log(`Using ${provider.name} (${provider.model})`);
 
@@ -116,8 +130,8 @@ export async function runAudit(opts) {
     explained = await explainFindings({ findings, plan, runs, gtmContainer, provider, lang, log });
   }
 
-  const outDir = path.resolve(opts.outDir ?? defaultOutDir());
-  const reportPath = await writeReports({ outDir, config, plan, runs, findings, explained, lang, branding: opts.branding ?? config.branding !== false });
+  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 counts = summarize(groupFindings(findings));
-  return { journeys, plan, runs, findings, explained, counts, reportPath, outDir, lang, ...(saveError ? { saveError } : {}) };
+  return { journeys, plan, runs, findings, explained, counts, reportPath, outDir, lang, ...(against ? { againstId: against.id } : {}), ...(saveError ? { saveError } : {}) };
 }

package/src/checks.js

@@ -110,7 +110,7 @@ function expectedIn(planEvent, journeyId) {
   return !planEvent.journeys || planEvent.journeys.includes(journeyId);
 }
 
-function isConsentCommand(entry, kind) {
+export function isConsentCommand(entry, kind) {
   return Array.isArray(entry.value) && entry.value[0] === "consent" && entry.value[1] === kind;
 }
 
@@ -444,3 +444,58 @@ export function groupFindings(findings) {
   }
   return [...groups.values()].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
 }
+
+const WRONG_VALUE_CHECKS = new Set(["purchase_value_invalid", "purchase_currency_invalid", "purchase_items_empty", "purchase_mismatch"]);
+export const PLAN_BUCKETS = ["implemented", "missing", "missing_params", "wrong_values", "unplanned", "not_checked"];
+
+/**
+ * Sorts every planned event into one bucket from the runs and the findings checkRun gave them:
+ * implemented, missing, missing_params, wrong_values or not_checked, plus one unplanned entry per
+ * event that fired but is not in the plan. Coverage = implemented / planned events that were checkable.
+ * @param {Plan} plan
+ * @param {any[]} runs
+ * @param {Finding[]} findings
+ */
+export function planCheck(plan, runs, findings) {
+  const events = (plan?.events ?? []).map((e) => ({ ...e, platform: String(e.platform ?? "").toLowerCase() }));
+  const entries = [];
+  for (const ev of events) {
+    const walked = runs.filter((r) => expectedIn(ev, r.journeyId) && (!r.providers || r.providers.includes(ev.platform)));
+    const entry = { platform: ev.platform, event: ev.name, bucket: "not_checked", journeys: [...new Set(walked.map((r) => r.journeyId))] };
+    if (walked.length) {
+      const own = findings.filter((f) => f.event && walked.some((r) => r.journeyId === f.journey && r.viewport === f.viewport) && hitMatchesEvent(ev, { platform: f.platform, name: f.event }));
+      const params = own.filter((f) => f.check === "missing_params");
+      const values = own.filter((f) => WRONG_VALUE_CHECKS.has(f.check));
+      const fired = walked.some((r) => r.hits.some((h) => hitMatchesEvent(ev, h)));
+      if (params.length) entry.bucket = "missing_params";
+      else if (values.length) entry.bucket = "wrong_values";
+      else entry.bucket = fired ? "implemented" : "missing";
+      const details = [...new Set([...params, ...values].map((f) => f.detail))];
+      if (details.length) entry.details = details;
+    }
+    entries.push(entry);
+  }
+  // Unplanned events, from the runs whose unplanned_events finding survived the --event filter.
+  const seen = new Set();
+  for (const r of runs) {
+    if (!findings.some((f) => f.check === "unplanned_events" && f.journey === r.journeyId && f.viewport === r.viewport)) continue;
+    for (const h of r.hits) {
+      if (events.some((e) => hitMatchesEvent(e, h)) || seen.has(key(h.platform, h.name))) continue;
+      seen.add(key(h.platform, h.name));
+      entries.push({ platform: h.platform, event: h.name, bucket: "unplanned", journeys: [r.journeyId] });
+    }
+  }
+  const score = (list) => {
+    const planned = list.filter((e) => e.bucket !== "unplanned");
+    const checkable = planned.filter((e) => e.bucket !== "not_checked").length;
+    const implemented = planned.filter((e) => e.bucket === "implemented").length;
+    return { implemented, checkable, not_checked: planned.length - checkable, percent: checkable ? Math.round((implemented / checkable) * 100) : null };
+  };
+  const platforms = [...new Set(entries.filter((e) => e.bucket !== "unplanned").map((e) => e.platform))];
+  const counts = Object.fromEntries(PLAN_BUCKETS.map((b) => [b, entries.filter((e) => e.bucket === b).length]));
+  return {
+    coverage: { ...score(entries), platforms: Object.fromEntries(platforms.map((p) => [p, score(entries.filter((e) => e.platform === p))])) },
+    counts,
+    events: entries,
+  };
+}

package/src/cli.js

@@ -3,77 +3,14 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { loadConfig, runAudit } from "./audit.js";
-import { LANGUAGES, messages } from "./i18n.js";
-import { PROVIDERS } from "./providers.js";
-import { JOURNEY_PRESETS } from "./journeys.js";
-import { PROVIDERS as TRACKING_PROVIDERS, DEFAULT_PROVIDERS } from "./parsers.js";
+import { messages } from "./i18n.js";
+import { helpText } from "./help.js";
 import { replaySavedSite, writeSavedSteps } from "./replay.js";
+import { savePlan } from "./plan.js";
+import { DEFAULT_DATA_DIR } from "./workspace.js";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
-const USAGE = `ai-tag-debugger: an open-source AI agent that QA-tests your analytics and ad tracking.
-
-Usage:
-  ai-tag-debugger run --site <url> --journey purchase [options]   Audit ready-made journeys, no config needed.
-  ai-tag-debugger run --site <url> --goal "<what to do>"          Audit a journey you describe in plain language.
-  ai-tag-debugger run --config <file> [options]                   Run an audit from a config file.
-  ai-tag-debugger replay <dir>... [--update]      Audit sites saved with --save-site again, offline and without AI,
-                                                  and list findings that changed. Exits with code 1 when any did.
-  ai-tag-debugger mcp [--http] [--port <n>]       Start the MCP server for Claude, ChatGPT, Gemini and other chat apps.
-
-Run options:
-  --site <url>         The site to audit (overrides "site" in the config).
-  --config <file>      Audit config (JSON). See examples/demo.config.json.
-  --journey <id>       Run this journey (repeatable): a journey id from the config, or a ready-made
-                       journey: ${Object.keys(JOURNEY_PRESETS).join(", ")}.
-  --goal "<text>"      Run a journey you describe in plain language (repeatable).
-  --events <names>     Only check these events, comma separated, e.g. purchase,add_to_cart.
-  --max-steps <n>      Most AI steps per journey (default 30). Lower it to cap API usage.
-  --out <dir>          Where to write report.html, report.md, timeline.csv and capture.json (default: reports/<timestamp>).
-  --provider <name>    AI provider: ${Object.keys(PROVIDERS).join(", ")} (default: whichever API key is set).
-  --model <id>         Model id (defaults: ${Object.entries(PROVIDERS).filter(([, p]) => p.defaultModel).map(([k, p]) => `${k} ${p.defaultModel}`).join(", ")}).
-  --base-url <url>     API address for --provider openai-compatible (Kimi, GLM, DeepSeek, OpenRouter, Ollama...).
-  --lang <code>        Report language: ${Object.keys(LANGUAGES).join(" or ")} (default: en, or "language" in the config).
-  --providers <list>   Tracking providers to check, comma separated (default: ${DEFAULT_PROVIDERS.join(",")}).
-                       Choose from ${Object.keys(TRACKING_PROVIDERS).join(", ")}. Requests to the
-                       others are still answered locally, but only counted ("providers" in the config).
-  --viewport <name>    Only run this viewport: desktop or mobile (repeatable).
-  --allow-host <host>  Let journeys visit this host too, e.g. a hosted checkout (repeatable). By default the
-                       browser stays on the audited site and its subdomains ("allowed_hosts" in the config).
-  --scripted           Replay each journey's fixed "steps" instead of letting the AI browse.
-  --no-ai              Use no AI model at all (requires --scripted). The report then has no explanations.
-  --fail-on <level>    Exit with code 1 when findings reach this level: broken, risk, warning or never (default: broken).
-  --headed             Show the browser window.
-  --keep-bodies        Store tracking requests as sent. By default, emails, phone numbers and user ids sent
-                       for ad matching are redacted in the report and capture.json ("keep_bodies" in the config).
-  --no-branding        Leave the Analitik İşler logo and credit line out of the reports ("branding": false in the config).
-  --save-site <dir>    Also save the site's responses and the steps taken in this folder, so "replay" can audit
-                       the same pages again offline. Its findings become the expected ones.
-  --save-steps <file>  Write the steps each journey took into "journeys[].steps" of this config file (created
-                       if missing), so "run --config <file> --scripted --no-ai" repeats them with no AI model
-                       or API key. A journey run on several viewports keeps the steps of the first.
-
-Replay options:
-  --update             Make this replay's findings the expected ones (after checking that the changes are right).
-  --out <dir>          Where to write the replay's reports (default: <dir>/last-replay).
-
-MCP options:
-  --http               Serve over Streamable HTTP instead of stdio (for apps that connect to a URL).
-  --port <n>           HTTP port (default 8787).
-  --host <addr>        HTTP host (default 127.0.0.1).
-  --token <secret>     Secret URL path segment, at least 16 characters (default: random, printed at start).
-  --allow-private-network  Over HTTP, let audits open localhost and private network addresses (blocked by default).
-  --reports <dir>      Where finished audits write reports (default: ~/ai-tag-debugger-reports).
-  --public-url <url>   The HTTPS address your tunnel or host gives this server, so audits can link to their reports.
-
-  -h, --help           Show this help.
-  -v, --version        Print the version.
-
-Short alias: aitd (aitd run ... is the same as ai-tag-debugger run ...).
-
-API keys: set one of ${Object.values(PROVIDERS).map((p) => p.env).join(", ")}.
-Any OpenAI-compatible API: --provider openai-compatible --base-url <url> --model <id>, with the key in OPENAI_COMPATIBLE_API_KEY.`;
-
 async function main() {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
@@ -86,6 +23,7 @@ async function main() {
       out: { type: "string" },
       journey: { type: "string", multiple: true },
       viewport: { type: "string", multiple: true },
+      platforms: { type: "string", multiple: true },
       providers: { type: "string", multiple: true },
       "allow-host": { type: "string", multiple: true },
       "allow-private-network": { type: "boolean", default: false },
@@ -108,6 +46,11 @@ async function main() {
       "save-site": { type: "string" },
       "save-steps": { type: "string" },
       update: { type: "boolean", default: false },
+      "data-dir": { type: "string" },
+      against: { type: "string" },
+      from: { type: "string" },
+      format: { type: "string" },
+      force: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", short: "v", default: false },
     },
@@ -145,19 +88,75 @@ async function main() {
     if (changed && !values.update) process.exitCode = 1;
     return;
   }
-  if (values.help || command !== "run" || (!values.config && !values.site)) {
-    console.log(USAGE);
-    process.exit(values.help ? 0 : 2);
+  if (command === "plan" && positionals[1] === "list" && !values.help) {
+    if (!values.site) throw new Error("plan list needs --site <url>: aitd plan list --site https://www.example.com");
+    const { domainOf, listPlanIds } = await import("./workspace.js");
+    const ids = await listPlanIds(values["data-dir"] ?? DEFAULT_DATA_DIR, values.site);
+    if (!ids.length) throw new Error(`No plan yet for ${domainOf(values.site)}. Draft one with: aitd plan --site ${values.site}`);
+    for (const id of ids) console.log(id);
+    return;
   }
-  if (values["no-ai"] && !values.scripted) {
-    throw new Error("--no-ai needs --scripted: without an AI model, journeys must have fixed steps.");
+  if (command === "plan" && !values.help && ["import", "export"].includes(positionals[1])) {
+    await planSheet(positionals[1], positionals[2], values);
+    return;
   }
+  if (command === "plan" && !values.help) {
+    if (values.from) throw new Error("--from was removed. Draft a plan with: aitd plan --site <url>");
+    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");
+    const dataDir = values["data-dir"] ?? DEFAULT_DATA_DIR;
+    const { domainOf } = await import("./workspace.js");
+    domainOf(values.site); // Checked before the browser starts.
+    const maxSteps = values["max-steps"] ? Number(values["max-steps"]) : undefined;
+    if (maxSteps !== undefined && !(Number.isInteger(maxSteps) && maxSteps > 0)) throw new Error("--max-steps must be a positive whole number.");
+    const { createProvider } = await import("./providers.js");
+    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 { 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);
+    console.log(`✓ Saved plan ${id}: ${plan.events.length} events (${custom} custom) and ${plan.user_properties.length} user properties in ${rel.startsWith("..") ? dir : rel}`);
+    return;
+  }
+  if (values.help || command !== "run" || (!values.config && !values.site && !values.against)) {
+    console.log(helpText(command));
+    process.exit(values.help ? 0 : 2);
+  }
+  if (values["no-ai"]) values.scripted = true; // Without an AI model the journeys can only replay fixed steps.
+  if (values.providers?.length) console.log("--providers is now --platforms.");
+  const platforms = [...(values.platforms ?? []), ...(values.providers ?? [])];
   const levels = ["broken", "risk", "warning"];
   const failOn = values["fail-on"];
   if (failOn !== "never" && !levels.includes(failOn)) throw new Error(`--fail-on must be one of ${levels.join(", ")}, never.`);
 
   const loaded = values.config ? await loadConfig(values.config) : { config: {}, plan: null, gtmContainer: null };
   if (values.site) loaded.config = { ...loaded.config, site: values.site };
+  if (!values.against && !values.journey?.length && !values.goal?.length && !loaded.config.journeys?.length) {
+    throw new Error('Nothing to test. Add --against latest, --journey <id> or --goal "<text>".');
+  }
+  let against = null;
+  if (values.against) {
+    const { readJson } = await import("./audit.js");
+    const { resolvePlan } = await import("./workspace.js");
+    if (loaded.config.site) {
+      try {
+        new URL(loaded.config.site);
+      } catch {
+        throw new Error(`"${loaded.config.site}" is not a full URL. Use e.g. https://www.example.com`);
+      }
+    }
+    against = await resolvePlan(values.against, { dataDir: values["data-dir"] ?? DEFAULT_DATA_DIR, site: loaded.config.site });
+    const plan = await readJson(against.file);
+    if (!Array.isArray(plan?.events)) throw new Error(`${against.file} is not a plan: it needs an "events" list.`);
+    if (!loaded.config.site) {
+      if (!plan.site) throw new Error(`${against.file} has no "site". Add --site <url>.`);
+      loaded.config = { ...loaded.config, site: plan.site };
+    }
+    loaded.plan = plan;
+  }
   if (values["keep-bodies"]) loaded.config = { ...loaded.config, keep_bodies: true };
   if (values["allow-host"]?.length) loaded.config = { ...loaded.config, allowed_hosts: [...(loaded.config.allowed_hosts ?? []), ...values["allow-host"]] };
   try {
@@ -167,6 +166,8 @@ async function main() {
   }
   const maxSteps = values["max-steps"] ? Number(values["max-steps"]) : undefined;
   if (maxSteps !== undefined && !(Number.isInteger(maxSteps) && maxSteps > 0)) throw new Error("--max-steps must be a positive whole number.");
+  // run --out is a hidden alias kept for one minor version; --data-dir replaces it.
+  if (values.out) console.log("Note: run --out will be removed in a later version. Runs are saved in aitd/<domain>/runs/<id>/; use --data-dir <dir> to keep them elsewhere.");
   const result = await runAudit({
     ...loaded,
     journeys: values.journey,
@@ -174,7 +175,7 @@ async function main() {
     events: (values.events ?? []).flatMap((e) => e.split(",")).map((e) => e.trim()).filter(Boolean),
     maxSteps,
     viewports: values.viewport,
-    providers: values.providers?.length ? values.providers.flatMap((p) => p.split(",")) : undefined,
+    providers: platforms.length ? platforms.flatMap((p) => p.split(",")) : undefined,
     scripted: values.scripted,
     ai: !values["no-ai"],
     provider: values.provider,
@@ -184,7 +185,9 @@ async function main() {
     headed: values.headed,
     branding: values["no-branding"] ? false : undefined,
     outDir: values.out,
+    dataDir: values["data-dir"],
     saveSite: values["save-site"],
+    against,
     log: (msg) => console.log(msg),
   });
 
@@ -209,6 +212,34 @@ async function main() {
   }
 }
 
+async function planSheet(action, arg, values) {
+  const dataDir = values["data-dir"] ?? DEFAULT_DATA_DIR;
+  const shown = (p) => {
+    const rel = path.relative(process.cwd(), p);
+    return rel.startsWith("..") ? p : rel;
+  };
+  const { readPlanSheet, writePlanSheet } = await import("./sheet.js");
+  if (action === "import") {
+    if (!arg) throw new Error("plan import needs a file: aitd plan import plan.xlsx --site https://www.example.com");
+    if (!values.site) throw new Error(`plan import needs --site <url>: aitd plan import ${arg} --site https://www.example.com`);
+    const { domainOf } = await import("./workspace.js");
+    domainOf(values.site);
+    const { plan, warnings } = await readPlanSheet(arg, { site: values.site });
+    for (const w of warnings) console.log(`Warning: ${w}`);
+    const { id, dir } = await savePlan(plan, { dataDir, site: values.site });
+    console.log(`✓ Imported plan ${id}: ${plan.events.length} events and ${plan.user_properties.length} user properties in ${shown(dir)}`);
+    return;
+  }
+  if (!arg) throw new Error("plan export needs a plan: aitd plan export latest --site https://www.example.com");
+  const format = (values.format ?? "xlsx").toLowerCase();
+  if (!["xlsx", "csv"].includes(format)) throw new Error(`--format must be xlsx or csv (found "${values.format}").`);
+  const { resolvePlan } = await import("./workspace.js");
+  const { file } = await resolvePlan(arg, { dataDir, site: values.site });
+  const plan = JSON.parse(readFileSync(file, "utf8"));
+  const written = await writePlanSheet(plan, path.dirname(file), { format });
+  console.log(`✓ Exported the plan to ${written.map(shown).join(" and ")}. Edit it, then save it as a new plan with: aitd plan import ${shown(written[0])} --site ${values.site ?? plan.site ?? "<url>"}`);
+}
+
 main().catch((err) => {
   console.error(`Error: ${err.message}`);
   process.exit(2);

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 };
+}