weftens 0.0.1 → 0.1.0

package/agent-cores/meta-ads/src/parse.mjs

@@ -0,0 +1,123 @@
+// Dependency-free CSV parser + Meta Ads Manager column mapper. A Meta export is a clean
+// header row followed by one row per breakdown level (campaign / ad set / ad). We find
+// the header by known column tokens, map arbitrary spellings to canonical field names,
+// and coerce currency / percent / number cells.
+
+// --- CSV tokenizer (state machine; handles quotes, embedded commas, CRLF) ---
+export function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  const s = String(text).replace(/^/, ''); // strip BOM
+
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (s[i + 1] === '"') { field += '"'; i += 1; }
+        else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') inQuotes = true;
+    else if (c === ',') { row.push(field); field = ''; }
+    else if (c === '\n') { row.push(field); field = ''; rows.push(row); row = []; }
+    else if (c === '\r') { /* handled by \n */ }
+    else field += c;
+  }
+  if (field.length > 0 || row.length > 0) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+function normHeader(h) {
+  return String(h).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+// canonical field -> normalized header spellings that map to it
+const ALIASES = {
+  campaign: ['campaign name', 'campaign'],
+  adset: ['ad set name', 'ad set', 'adset name', 'adset'],
+  ad: ['ad name', 'ad'],
+  spend: ['amount spent usd', 'amount spent', 'spend'],
+  impressions: ['impressions', 'impr'],
+  reach: ['reach'],
+  frequency: ['frequency'],
+  results: ['results', 'result'],
+  resultType: ['result indicator', 'result type', 'result name'],
+  costPerResult: ['cost per result', 'cost per results'],
+  linkClicks: ['link clicks', 'clicks all', 'clicks'],
+  ctr: ['ctr link click through rate', 'ctr all', 'ctr'],
+  purchases: ['purchases', 'website purchases'],
+  purchaseValue: ['purchases conversion value', 'website purchases conversion value', 'purchase conversion value'],
+  roas: ['purchase roas return on ad spend', 'website purchase roas', 'purchase roas', 'roas'],
+};
+
+const HEADER_TO_FIELD = (() => {
+  const m = new Map();
+  for (const [field, spellings] of Object.entries(ALIASES)) for (const sp of spellings) m.set(sp, field);
+  return m;
+})();
+
+const PERCENT_FIELDS = new Set(['ctr']);
+const NUMERIC_FIELDS = new Set([
+  'spend', 'impressions', 'reach', 'frequency', 'results', 'costPerResult',
+  'linkClicks', 'purchases', 'purchaseValue', 'roas',
+]);
+
+export function toNumber(raw) {
+  if (raw == null) return null;
+  let v = String(raw).trim();
+  if (v === '' || v === '--' || v === '—' || v.toLowerCase() === 'n/a') return null;
+  v = v.replace(/[$£€,%\s"]/g, '');
+  if (v === '') return null;
+  const n = Number.parseFloat(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+// Percent cell -> fraction. "0.30%" -> 0.003, "1.00%" -> 0.01, bare "0.3" -> 0.003.
+export function toPercent(raw) {
+  if (raw == null) return null;
+  const v = String(raw).trim();
+  if (v === '' || v === '--' || v === '—') return null;
+  const hadPercent = v.includes('%');
+  const n = toNumber(v);
+  if (n == null) return null;
+  return hadPercent ? n / 100 : (n > 1 ? n / 100 : n);
+}
+
+function coerce(field, raw) {
+  if (PERCENT_FIELDS.has(field)) return toPercent(raw);
+  if (NUMERIC_FIELDS.has(field)) return toNumber(raw);
+  return raw == null ? '' : String(raw).trim();
+}
+
+function findHeader(rows, minKnown = 3) {
+  for (let i = 0; i < rows.length; i += 1) {
+    const mapped = rows[i].map((h) => HEADER_TO_FIELD.get(normHeader(h))).filter(Boolean);
+    if (new Set(mapped).size >= minKnown) return i;
+  }
+  return -1;
+}
+
+// Parse a Meta Ads Manager CSV export into canonical row objects.
+export function parseReport(text) {
+  const rows = parseCsv(text);
+  const headerIdx = findHeader(rows);
+  if (headerIdx === -1) {
+    throw new Error('No recognizable Meta Ads header row found (need e.g. "Ad set name", "Amount spent", "Results").');
+  }
+  const colField = rows[headerIdx].map((h) => HEADER_TO_FIELD.get(normHeader(h)) || null);
+
+  const out = [];
+  for (let i = headerIdx + 1; i < rows.length; i += 1) {
+    const cells = rows[i];
+    if (cells.every((c) => (c || '').trim() === '')) continue;
+    const rec = {};
+    for (let c = 0; c < colField.length; c += 1) {
+      const field = colField[c];
+      if (field) rec[field] = coerce(field, cells[c]);
+    }
+    // require at least one identifying name so we don't emit garbage rows
+    if (rec.ad || rec.adset || rec.campaign) out.push(rec);
+  }
+  return out;
+}

package/agent-cores/meta-ads/test/analyze.test.js

@@ -0,0 +1,72 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { parseReport } from '../src/parse.mjs';
+import { analyze, DEFAULT_THRESHOLDS } from '../src/analyze.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const fixture = () => parseReport(readFileSync(join(HERE, 'fixtures', 'meta-ads.csv'), 'utf8'));
+const find = (result, entity) => result.changes.find((c) => c.evidence.entity === entity);
+
+test('parse maps Meta columns and coerces numbers/percent', () => {
+  const rows = fixture();
+  assert.equal(rows.length, 5);
+  const a = rows.find((r) => r.ad === 'Video A');
+  assert.equal(a.spend, 85);
+  assert.equal(a.results, 0);
+  assert.equal(a.frequency, 1.25);
+  assert.equal(rows.find((r) => r.ad === 'Video E').ctr, 0.01); // "1.00%" -> 0.01
+});
+
+test('the whole sheet is propose-only', () => {
+  assert.equal(analyze(fixture()).proposeOnly, true);
+});
+
+test('pause: spend with zero results is flagged', () => {
+  const r = find(analyze(fixture()), 'Video A');
+  assert.equal(r.type, 'pause');
+  assert.equal(r.dollars, 85);
+});
+
+test('low-roas: ROAS below break-even is flagged as a loss', () => {
+  const r = find(analyze(fixture()), 'Story C'); // roas 0.6, spend 70
+  assert.equal(r.type, 'low-roas');
+  assert.equal(r.dollars, 28); // 70 - 70*0.6
+});
+
+test('inefficient: cost/result far above account average is flagged (not double-counted as low-roas)', () => {
+  const r = find(analyze(fixture()), 'Image D'); // cpr 80 vs ~26 account, roas 1.3 (profitable)
+  assert.equal(r.type, 'inefficient');
+  assert.ok(r.evidence.costPerResult >= 3 * r.evidence.accountCPR);
+});
+
+test('fatigue: high frequency triggers a creative-refresh proposal', () => {
+  const r = find(analyze(fixture()), 'Carousel B'); // frequency 4.8
+  assert.equal(r.type, 'fatigue');
+});
+
+test('a healthy ad produces no finding', () => {
+  assert.equal(find(analyze(fixture()), 'Video E'), undefined);
+});
+
+test('changes are ranked by dollars, descending', () => {
+  const { changes } = analyze(fixture());
+  for (let i = 1; i < changes.length; i += 1) {
+    assert.ok((changes[i - 1].dollars || 0) >= (changes[i].dollars || 0));
+    assert.equal(changes[i].rank, i + 1);
+  }
+});
+
+test('empty input yields a clean, empty propose-only sheet', () => {
+  const result = analyze([]);
+  assert.equal(result.changes.length, 0);
+  assert.match(result.summary, /No pause/);
+});
+
+test('thresholds are overridable', () => {
+  assert.equal(typeof DEFAULT_THRESHOLDS.fatigueFrequency, 'number');
+  const strict = analyze(fixture(), { thresholds: { fatigueFrequency: 10 } });
+  assert.equal(strict.changes.find((c) => c.type === 'fatigue'), undefined);
+});

package/agent-cores/meta-ads/test/fixtures/meta-ads.csv

@@ -0,0 +1,6 @@
+Campaign name,Ad set name,Ad name,Amount spent (USD),Impressions,Reach,Frequency,Results,Result indicator,Cost per result,Link clicks,CTR (link click-through rate),Purchases,Purchase ROAS (return on ad spend)
+Prospecting,Broad Interests,Video A,85.00,40000,32000,1.25,0,actions:purchase,,120,0.30%,0,
+Prospecting,Lookalike 1%,Carousel B,120.00,90000,18750,4.80,6,actions:purchase,20.00,300,0.33%,6,2.10
+Retargeting,Cart Abandoners 7d,Story C,70.00,15000,12000,1.25,1,actions:purchase,70.00,45,0.30%,1,0.60
+Prospecting,Interest - Cooking,Image D,80.00,20000,17500,1.14,1,actions:purchase,80.00,60,0.30%,1,1.30
+Retargeting,Site Visitors 30d,Video E,90.00,20000,16000,1.25,9,actions:purchase,10.00,200,1.00%,9,3.50

package/agent-cores/paid-search/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/paid-search",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Google Ads paid-search auditor. Deterministic: parse exported search-terms + campaign reports, compute a ranked change sheet (negatives, budget moves, structure fixes). PROPOSE-ONLY. No LLM in the core.",
+  "bin": {
+    "paid-search": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "audit": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/agent-cores/paid-search/src/analyze.mjs

@@ -0,0 +1,303 @@
+// Deterministic Google Ads paid-search analysis. No LLM. PROPOSE-ONLY.
+//
+// Input: parsed search-terms rows and campaign-performance rows (canonical fields
+// from parse.mjs). Output: a ranked change sheet. Every row carries the evidence
+// numbers that triggered it. The core never calls a model and never touches an
+// account — a human applies the proposed changes.
+//
+// Three finding families, mirroring the job:
+//   negative  — search terms burning spend with no/poor return (add as negatives)
+//   budget    — converting campaigns throttled by budget (raise / reallocate)
+//   structure — root-cause fixes (starved Smart Bidding, shared-budget starvation)
+//               that outrank the budget moves they explain.
+
+export const DEFAULT_THRESHOLDS = {
+  // Negatives (irrelevant / zero-conversion queries).
+  negMinClicks: 15, // enough traffic that "0 conversions" is signal, not noise
+  negMinCost: 1, // ignore trivial spend
+  // Negatives (inefficient: converting but far above account CPA).
+  effCpaMultiple: 3, // term CPA >= 3x account CPA
+  effMinCost: 20,
+  // Budget moves.
+  lostIsBudgetMin: 0.1, // >=10% eligible impressions lost to budget
+  lostIsBudgetStrangled: 0.3, // >=30% => campaign is being strangled
+  // Structure: Smart Bidding conversion floor (Google rule of thumb ~15-30/30d).
+  biddingMinConv: 30,
+};
+
+const SMART_BIDDING = /target\s*cpa|troas|target\s*roas|maximize\s*conv|maximise\s*conv/i;
+
+function sum(arr, f) {
+  let t = 0;
+  for (const x of arr) { const v = f(x); if (Number.isFinite(v)) t += v; }
+  return t;
+}
+
+function round(n, dp = 2) {
+  if (!Number.isFinite(n)) return n;
+  const m = 10 ** dp;
+  return Math.round(n * m) / m;
+}
+
+// Impression-share opportunity math for a budget-throttled campaign.
+// eligible = impressions / searchIS ; impressions lost to budget = eligible * lostISBudget.
+// Additional clicks/conv/cost/value scale off the campaign's own CTR / CVR / CPC / value.
+// This is an UPPER bound: CTR and CVR usually soften as volume grows.
+function budgetOpportunity(c, thresholds) {
+  const clicks = c.clicks || 0;
+  const cost = c.cost || 0;
+  const conv = c.conversions || 0;
+  const value = c.convValue || 0;
+  const is = c.searchIS;
+  const lost = c.lostISBudget || 0;
+
+  // scaleFactor = how much more share we could capture relative to what we capture now.
+  // Prefer the direct impression math when searchIS is known; else scale by share ratio.
+  let scaleFactor;
+  if (Number.isFinite(is) && is > 0) {
+    scaleFactor = lost / is;
+  } else {
+    scaleFactor = lost / Math.max(1 - lost, 0.01);
+  }
+  const addClicks = clicks * scaleFactor;
+  const cvr = clicks > 0 ? conv / clicks : 0;
+  const cpc = clicks > 0 ? cost / clicks : 0;
+  const valuePerConv = conv > 0 ? value / conv : 0;
+  const addConv = addClicks * cvr;
+  const addCost = addClicks * cpc;
+  const addValue = addConv * valuePerConv;
+  return {
+    scaleFactor: round(scaleFactor, 4),
+    addClicks: Math.round(addClicks),
+    addConv: round(addConv, 1),
+    addCost: round(addCost, 2),
+    addValue: round(addValue, 2),
+    valuePerConv: round(valuePerConv, 2),
+  };
+}
+
+export function analyze(input = {}, options = {}) {
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...(options.thresholds || {}) };
+  const searchTerms = Array.isArray(input.searchTerms) ? input.searchTerms : [];
+  const campaigns = Array.isArray(input.campaigns) ? input.campaigns : [];
+
+  // --- account-level aggregates from the search-terms report ---
+  const totalClicks = sum(searchTerms, (t) => t.clicks);
+  const totalCost = sum(searchTerms, (t) => t.cost);
+  const totalConv = sum(searchTerms, (t) => t.conversions);
+  const totalConvValue = sum(searchTerms, (t) => t.convValue);
+  const accountCVR = totalClicks > 0 ? totalConv / totalClicks : 0;
+  const accountCPA = totalConv > 0 ? totalCost / totalConv : null;
+  const accountValuePerConv = totalConv > 0 ? totalConvValue / totalConv : null;
+
+  const changes = [];
+
+  // --- 1. Negatives: irrelevant / zero-conversion queries ---
+  for (const t of searchTerms) {
+    const clicks = t.clicks || 0;
+    const cost = t.cost || 0;
+    const conv = t.conversions || 0;
+    if (conv === 0 && clicks >= thresholds.negMinClicks && cost >= thresholds.negMinCost) {
+      const expectedConv = round(clicks * accountCVR, 1);
+      changes.push({
+        type: 'negative',
+        subtype: 'irrelevant',
+        change: `Add "${t.searchTerm}" as a negative keyword`,
+        where: t.campaign ? `campaign: ${t.campaign}${t.adGroup ? ` / ${t.adGroup}` : ''}` : 'account level',
+        why: `${clicks} clicks, $${round(cost)} spent, 0 conversions`
+          + (accountCVR > 0 ? ` (expected ~${expectedConv} at the ${round(accountCVR * 100, 1)}% account conversion rate)` : ''),
+        expectedEffect: `Recover ~$${round(cost)}/period of wasted spend`,
+        risk: 'If the query is actually relevant, you forfeit those impressions — confirm intent before excluding.',
+        dollars: round(cost),
+        evidence: {
+          searchTerm: t.searchTerm, campaign: t.campaign ?? null,
+          clicks, cost: round(cost), conversions: conv, expectedConv,
+        },
+      });
+    } else if (
+      conv > 0 && accountCPA != null && cost >= thresholds.effMinCost
+      && cost / conv >= thresholds.effCpaMultiple * accountCPA
+    ) {
+      // inefficient: converting, but paying far above the account's cost per conversion
+      const termCpa = cost / conv;
+      const overspend = cost - conv * accountCPA;
+      changes.push({
+        type: 'negative',
+        subtype: 'inefficient',
+        change: `Bid down or restrict "${t.searchTerm}" (or add as negative if off-intent)`,
+        where: t.campaign ? `campaign: ${t.campaign}${t.adGroup ? ` / ${t.adGroup}` : ''}` : 'account level',
+        why: `CPA $${round(termCpa)} vs account $${round(accountCPA)} (${round(termCpa / accountCPA, 1)}x); `
+          + `$${round(cost)} for ${round(conv, 1)} conv`,
+        expectedEffect: `Recover ~$${round(overspend)}/period of over-target spend`,
+        risk: 'Converting term — restricting too hard can cut real volume; prefer a bid cut first.',
+        dollars: round(overspend),
+        evidence: {
+          searchTerm: t.searchTerm, campaign: t.campaign ?? null,
+          cost: round(cost), conversions: round(conv, 1),
+          termCpa: round(termCpa), accountCPA: round(accountCPA),
+        },
+      });
+    }
+  }
+
+  // --- 2 & 3. Campaign-level: budget moves and structure fixes ---
+  const byCampaign = new Map();
+  for (const c of campaigns) if (c.campaign) byCampaign.set(c.campaign, c);
+
+  // group campaigns by shared budget pool for structure analysis
+  const pools = new Map();
+  for (const c of campaigns) {
+    if (!c.sharedBudget) continue;
+    if (!pools.has(c.sharedBudget)) pools.set(c.sharedBudget, []);
+    pools.get(c.sharedBudget).push(c);
+  }
+
+  // maps campaign -> the largest related budget-opportunity dollars (for structure ranking)
+  const budgetDollarsByCampaign = new Map();
+
+  for (const c of campaigns) {
+    const conv = c.conversions || 0;
+    const lost = c.lostISBudget || 0;
+    if (lost >= thresholds.lostIsBudgetMin && conv > 0) {
+      const opp = budgetOpportunity(c, thresholds);
+      const strangled = lost >= thresholds.lostIsBudgetStrangled;
+      const dollars = opp.addValue > 0 ? opp.addValue
+        : (accountCPA != null ? round(opp.addConv * accountCPA, 2) : opp.addConv);
+      budgetDollarsByCampaign.set(
+        c.campaign,
+        Math.max(budgetDollarsByCampaign.get(c.campaign) || 0, dollars),
+      );
+      changes.push({
+        type: 'budget',
+        subtype: strangled ? 'strangled' : 'throttled',
+        change: strangled
+          ? `Raise budget (or reallocate to) "${c.campaign}" — it is being strangled`
+          : `Raise budget for "${c.campaign}"`,
+        where: `campaign: ${c.campaign}`,
+        why: `${round(lost * 100, 1)}% of eligible impressions lost to budget, `
+          + `${round(conv, 1)} conversions at ${Number.isFinite(c.searchIS) ? round(c.searchIS * 100, 1) + '% impr. share' : 'unknown share'}`,
+        expectedEffect: `~+${opp.addClicks} clicks, +${opp.addConv} conv`
+          + (opp.addValue > 0 ? `, +$${opp.addValue} value` : '')
+          + ` at ~$${opp.addCost} more spend (upper bound)`,
+        risk: 'Scaling assumes current CTR/CVR hold as volume grows; they usually soften. Treat as a ceiling.',
+        dollars,
+        evidence: {
+          campaign: c.campaign, lostISBudget: round(lost, 4),
+          searchIS: Number.isFinite(c.searchIS) ? round(c.searchIS, 4) : null,
+          conversions: round(conv, 1), ...opp,
+        },
+      });
+    }
+  }
+
+  // Structure: Smart Bidding starved of conversion signal
+  for (const c of campaigns) {
+    const strat = c.biddingStrategy || '';
+    const conv = c.conversions || 0;
+    if (SMART_BIDDING.test(strat) && conv < thresholds.biddingMinConv) {
+      const atRisk = round(c.cost || 0);
+      const related = budgetDollarsByCampaign.get(c.campaign) || 0;
+      changes.push({
+        type: 'structure',
+        subtype: 'smart-bidding-starved',
+        change: `Fix bidding on "${c.campaign}" before touching budget — "${strat}" is starved of conversion signal`,
+        where: `campaign: ${c.campaign}`,
+        why: `${round(conv, 1)} conversions in the period is below the ~${thresholds.biddingMinConv}/30d Smart Bidding needs; `
+          + `$${atRisk} of spend is governed by a mis-calibrated bid strategy`,
+        expectedEffect: 'Consolidate conversion volume or switch to Maximize Clicks / manual until signal is sufficient; pacing issues here usually resolve once bidding has data',
+        risk: 'Bid-strategy changes trigger a new learning window; expect 1-2 weeks of unstable performance.',
+        dollars: atRisk,
+        // rank at/above any budget move on the same campaign (structure outranks budget)
+        rankValue: Math.max(atRisk, related + 0.01),
+        evidence: {
+          campaign: c.campaign, biddingStrategy: strat,
+          conversions: round(conv, 1), cost: atRisk, floor: thresholds.biddingMinConv,
+        },
+      });
+    }
+  }
+
+  // Structure: shared budget pool starving converting campaigns
+  for (const [poolName, members] of pools) {
+    if (members.length < 2) continue;
+    const throttled = members.filter((c) => (c.lostISBudget || 0) >= thresholds.lostIsBudgetMin && (c.conversions || 0) > 0);
+    if (throttled.length === 0) continue;
+    let poolDollars = 0;
+    const detail = [];
+    for (const c of throttled) {
+      const opp = budgetOpportunity(c, thresholds);
+      const d = opp.addValue > 0 ? opp.addValue
+        : (accountCPA != null ? round(opp.addConv * accountCPA, 2) : opp.addConv);
+      poolDollars += d;
+      detail.push({ campaign: c.campaign, lostISBudget: round(c.lostISBudget || 0, 4), addConv: opp.addConv, addValue: opp.addValue });
+    }
+    poolDollars = round(poolDollars, 2);
+    changes.push({
+      type: 'structure',
+      subtype: 'shared-budget-starve',
+      change: `Split or resize shared budget "${poolName}" — one pool is starving ${throttled.length} converting campaign(s)`,
+      where: `shared budget: ${poolName} (${members.map((m) => m.campaign).join(', ')})`,
+      why: `${throttled.length} converting campaign(s) losing impression share to a single shared pool: `
+        + throttled.map((c) => `${c.campaign} ${round((c.lostISBudget || 0) * 100, 1)}%`).join(', '),
+      expectedEffect: `Give throttled campaigns their own budgets; unlocks ~$${poolDollars} of value (aggregate upper bound)`,
+      risk: 'Splitting a pool removes automatic cross-campaign smoothing; monitor the others do not now underspend.',
+      dollars: poolDollars,
+      rankValue: poolDollars, // aggregate root cause, already large
+      evidence: { pool: poolName, members: members.map((m) => m.campaign), throttled: detail },
+    });
+  }
+
+  // --- rank the change sheet ---
+  // Primary: dollars of impact (rankValue lets structure sit at/above related budget moves).
+  // Tiebreak: type (structure < negative < budget), then a stable string key.
+  const typeRank = { structure: 0, negative: 1, budget: 2 };
+  const keyed = changes.map((c, i) => ({ ...c, rankValue: Number.isFinite(c.rankValue) ? c.rankValue : (c.dollars || 0), _i: i }));
+  keyed.sort((a, b) => {
+    if (b.rankValue !== a.rankValue) return b.rankValue - a.rankValue;
+    if (typeRank[a.type] !== typeRank[b.type]) return typeRank[a.type] - typeRank[b.type];
+    const ka = `${a.type}:${a.subtype}:${a.change}`;
+    const kb = `${b.type}:${b.subtype}:${b.change}`;
+    return ka < kb ? -1 : ka > kb ? 1 : a._i - b._i;
+  });
+  const ranked = keyed.map(({ _i, ...c }, idx) => ({ rank: idx + 1, ...c }));
+
+  const recoverable = round(
+    sum(ranked.filter((c) => c.type === 'negative'), (c) => c.dollars),
+    2,
+  );
+  const opportunity = round(
+    sum(ranked.filter((c) => c.type === 'budget'), (c) => c.dollars),
+    2,
+  );
+
+  return {
+    proposeOnly: true,
+    account: {
+      searchTermRows: searchTerms.length,
+      campaignRows: campaigns.length,
+      totalClicks,
+      totalCost: round(totalCost),
+      totalConversions: round(totalConv, 1),
+      accountCVR: round(accountCVR, 4),
+      accountCPA: accountCPA == null ? null : round(accountCPA),
+      accountValuePerConv: accountValuePerConv == null ? null : round(accountValuePerConv),
+    },
+    counts: {
+      total: ranked.length,
+      negatives: ranked.filter((c) => c.type === 'negative').length,
+      budget: ranked.filter((c) => c.type === 'budget').length,
+      structure: ranked.filter((c) => c.type === 'structure').length,
+    },
+    wastedSpendRecoverable: recoverable,
+    budgetOpportunityValue: opportunity,
+    summary: buildSummary(ranked, recoverable, opportunity),
+    changes: ranked,
+  };
+}
+
+function buildSummary(ranked, recoverable, opportunity) {
+  if (ranked.length === 0) return 'No negative, budget, or structure changes found in the exported reports.';
+  const top = ranked[0];
+  return `${ranked.length} proposed change(s); ~$${recoverable} recoverable from negatives, `
+    + `~$${opportunity} budget opportunity. Start with: ${top.change}.`;
+}

package/agent-cores/paid-search/src/cli.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Real CLI. PROPOSE-ONLY — reads exported Google Ads reports, prints a ranked
+// change sheet as JSON on stdout and a one-line summary on stderr. No account access.
+//
+// Modes:
+//   paid-search --search-terms <csv> [--campaigns <csv>] [--pretty]
+//   paid-search --campaigns <csv> [--search-terms <csv>]
+//   paid-search <input.json>        JSON: { "searchTerms": [...], "campaigns": [...] }
+
+import { readFileSync } from 'node:fs';
+import { analyze } from './analyze.mjs';
+import { parseReport } from './parse.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--search-terms' || a === '-s') args.searchTerms = argv[++i];
+    else if (a === '--campaigns' || a === '-c') args.campaigns = argv[++i];
+    else if (a === '--pretty') args.pretty = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.searchTerms && !args.campaigns && args._.length === 0) {
+    console.error('Usage: paid-search --search-terms <csv> [--campaigns <csv>] [--pretty]');
+    console.error('       paid-search <input.json>   (keys: searchTerms, campaigns)');
+    process.exitCode = 1;
+    return;
+  }
+
+  let input = { searchTerms: [], campaigns: [] };
+
+  if (args._.length > 0 && !args.searchTerms && !args.campaigns) {
+    const parsed = JSON.parse(readFileSync(args._[0], 'utf8'));
+    input.searchTerms = parsed.searchTerms || [];
+    input.campaigns = parsed.campaigns || [];
+  } else {
+    if (args.searchTerms) input.searchTerms = parseReport(readFileSync(args.searchTerms, 'utf8'));
+    if (args.campaigns) input.campaigns = parseReport(readFileSync(args.campaigns, 'utf8'));
+  }
+
+  const result = analyze(input);
+  console.error(`paid-search: ${result.summary}`);
+  console.log(JSON.stringify(result, null, args.pretty ? 2 : 0));
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+}