weftens 0.0.1 → 0.1.0

package/agent-cores/content-ops/src/parse.mjs

@@ -0,0 +1,121 @@
+// Dependency-free parsing for CMS exports. Two input shapes:
+//   - CSV (RFC-4180-ish: quoted fields, escaped quotes "", commas/newlines inside quotes)
+//   - JSON (an array of row objects, or { rows: [...] } / { items: [...] })
+//
+// Both normalize to an array of raw row objects keyed by the export's own headers.
+// Field-name normalization to the canonical schema happens in inventory.mjs.
+
+// --- CSV ---
+
+// State-machine parser. Handles quoted fields, "" escapes, and CR/LF inside quotes.
+// Returns an array of arrays (rows of string cells).
+export function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  let i = 0;
+  const n = text.length;
+  let started = false; // did we see any char on this line?
+
+  const pushField = () => {
+    row.push(field);
+    field = '';
+  };
+  const pushRow = () => {
+    row.push(field);
+    field = '';
+    rows.push(row);
+    row = [];
+    started = false;
+  };
+
+  while (i < n) {
+    const c = text[i];
+
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i += 2;
+          continue;
+        }
+        inQuotes = false;
+        i += 1;
+        continue;
+      }
+      field += c;
+      i += 1;
+      continue;
+    }
+
+    if (c === '"') {
+      inQuotes = true;
+      started = true;
+      i += 1;
+      continue;
+    }
+    if (c === ',') {
+      pushField();
+      started = true;
+      i += 1;
+      continue;
+    }
+    if (c === '\r') {
+      // swallow CR; handle the LF (or lone CR) as the line break
+      if (text[i + 1] === '\n') i += 1;
+      pushRow();
+      i += 1;
+      continue;
+    }
+    if (c === '\n') {
+      pushRow();
+      i += 1;
+      continue;
+    }
+    field += c;
+    started = true;
+    i += 1;
+  }
+
+  // flush trailing field/row if the file doesn't end in a newline
+  if (field.length > 0 || row.length > 0 || started) pushRow();
+
+  return rows;
+}
+
+// CSV text -> array of row objects keyed by header. Blank lines are dropped.
+export function csvToRecords(text) {
+  const rows = parseCsv(text).filter((r) => !(r.length === 1 && r[0].trim() === ''));
+  if (rows.length === 0) return [];
+  const headers = rows[0].map((h) => h.trim());
+  const records = [];
+  for (let r = 1; r < rows.length; r += 1) {
+    const cells = rows[r];
+    const obj = {};
+    for (let c = 0; c < headers.length; c += 1) {
+      obj[headers[c]] = cells[c] !== undefined ? cells[c] : '';
+    }
+    records.push(obj);
+  }
+  return records;
+}
+
+// --- dispatch ---
+
+// Auto-detect JSON vs CSV from the text and return raw row objects.
+export function parseExport(text, hint = null) {
+  const trimmed = text.replace(/^/, '').trimStart(); // strip BOM
+  const looksJson = hint === 'json' || (hint !== 'csv' && (trimmed.startsWith('[') || trimmed.startsWith('{')));
+
+  if (looksJson) {
+    const data = JSON.parse(trimmed);
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.rows)) return data.rows;
+    if (data && Array.isArray(data.items)) return data.items;
+    if (data && Array.isArray(data.records)) return data.records;
+    throw new Error('JSON export must be an array, or an object with a rows/items/records array.');
+  }
+
+  return csvToRecords(text);
+}

package/agent-cores/content-ops/test/fixtures/cms-export.csv

@@ -0,0 +1,13 @@
+url,title,published,last-updated,word count,pageviews,meta description,author
+https://acme.example/old-news-2019,Old News From 2019,2019-01-10,2019-01-15,800,12,An announcement from early 2019 that has not been touched since.,J. Smith
+https://acme.example/tags/misc,Miscellaneous Tag Archive Page,2025-12-20,2026-01-01,90,8,,A. Bot
+https://acme.example/pricing-guide,Pricing Guide,2022-06-01,2024-03-01,2400,4200,"This is a deliberately overlong meta description written to exceed the recommended one hundred and sixty character ceiling so the engine flags it as too long for a snippet.",M. Lee
+https://acme.example/,Acme — Home,2020-01-01,2026-06-15,650,9000,"The homepage of Acme, updated recently and carrying the most traffic on the whole site.",Team
+https://acme.example/blog/mid-article,A Mid-Traffic Article Worth Refreshing,2021-04-01,2025-05-01,1200,30,A long-form article with modest traffic that has aged past a year without a refresh.,J. Smith
+https://acme.example/blog/new-post,A Freshly Published Post,2026-06-18,2026-06-20,900,20,A brand new post that has not accumulated traffic yet but is current.,A. Bot
+https://acme.example/docs/reference,The Complete and Exhaustive Reference Documentation for Every Single Public API Endpoint,2019-05-01,2023-01-01,5000,200,Long-lived reference doc with steady moderate traffic that has decayed past two years.,M. Lee
+https://acme.example/guide,Complete Guide,2024-01-01,2026-03-01,1800,300,A moderately trafficked guide kept current within the last few months of the reporting window.,Team
+https://acme.example/reports/quarterly,Quarterly Report Archive,2025-01-01,2025-01-01,700,,An archived report where the traffic column was never populated by the analytics export.,J. Smith
+https://acme.example/team/jane-doe,Jane Doe,2026-04-01,2026-05-01,400,600,,Team
+https://acme.example/guide-legacy,Complete Guide,2023-10-01,2026-02-01,1500,150,A second page sharing the exact same title as the primary guide — a taxonomy collision.,Team
+https://acme.example/orphan,Orphaned Page With No Dates,,,200,5,A page whose export row is missing both the published and the last-updated date fields.,A. Bot

package/agent-cores/content-ops/test/fixtures/cms-export.json

@@ -0,0 +1,31 @@
+{
+  "rows": [
+    {
+      "url": "https://acme.example/legacy-faq",
+      "title": "Legacy FAQ",
+      "published": "2018-03-01",
+      "lastUpdated": "2018-09-01",
+      "wordCount": 1100,
+      "pageviews": 7,
+      "metaDescription": "An old FAQ nobody has updated in years and almost nobody reads."
+    },
+    {
+      "url": "https://acme.example/flagship",
+      "title": "Flagship Product Overview",
+      "published": "2021-01-01",
+      "lastUpdated": "2023-06-01",
+      "wordCount": 2200,
+      "pageviews": 8800,
+      "metaDescription": "The overview page for the flagship product, high traffic but overdue for a refresh."
+    },
+    {
+      "url": "https://acme.example/whats-new",
+      "title": "What's New",
+      "published": "2026-05-01",
+      "lastUpdated": "2026-05-15",
+      "wordCount": 500,
+      "pageviews": 640,
+      "metaDescription": "The most recent changelog entry with strong traffic and a current date."
+    }
+  ]
+}

package/agent-cores/content-ops/test/inventory.test.mjs

@@ -0,0 +1,177 @@
+// Offline tests — run with `node --test`, zero install. Asserts the engine makes
+// the specific keep/update/retire decisions the seeded fixture demands, flags the
+// seeded metadata gaps, and is deterministic. If these pass, the core is doing real
+// arithmetic on real data — not echoing a prompt.
+
+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 { inventoryFromText, buildInventory, DEFAULT_THRESHOLDS } from '../src/inventory.mjs';
+import { parseCsv, csvToRecords } from '../src/parse.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csvText = readFileSync(join(__dirname, 'fixtures', 'cms-export.csv'), 'utf8');
+const jsonText = readFileSync(join(__dirname, 'fixtures', 'cms-export.json'), 'utf8');
+
+// Pin asOf so hand-computed staleness matches the seeded expectations.
+const ASOF = '2026-07-01';
+const run = () => inventoryFromText(csvText, 'csv', { asOf: ASOF });
+const byUrl = (r, u) => r.items.find((it) => it.url === u);
+
+test('CSV parser handles quoted fields with embedded commas', () => {
+  const rows = parseCsv('a,b\n"x, y",z\n');
+  assert.deepEqual(rows, [['a', 'b'], ['x, y', 'z']]);
+  // the seeded homepage row has a comma inside a quoted meta description
+  const recs = csvToRecords(csvText);
+  const home = recs.find((r) => r.url === 'https://acme.example/');
+  assert.equal(home.author, 'Team', 'quoted comma must not shift the author column');
+  assert.match(home['meta description'], /Acme, updated recently/);
+});
+
+test('retires stale + low-traffic content with a redirect requirement', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/old-news-2019');
+  assert.equal(it.decision, 'retire');
+  assert.match(it.reasons.join(' '), /stale.*low traffic|low traffic.*stale/);
+  assert.equal(it.redirectTarget, null, 'redirect target is an unresolved decision, not omitted');
+});
+
+test('retires thin + low-traffic content as ROT even when recent', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/tags/misc');
+  assert.equal(it.decision, 'retire');
+  assert.match(it.reasons.join(' '), /thin content/);
+});
+
+test('updates high-traffic pages that have gone stale (never retires them)', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/pricing-guide');
+  assert.equal(it.decision, 'update');
+  assert.match(it.reasons.join(' '), /high traffic/);
+});
+
+test('keeps high-traffic fresh content', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/');
+  assert.equal(it.decision, 'keep');
+});
+
+test('updates a low-but-aging article that is not yet ROT', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/blog/mid-article');
+  assert.equal(it.decision, 'update');
+});
+
+test('updates decayed moderate-traffic reference docs', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/docs/reference');
+  assert.equal(it.decision, 'update');
+});
+
+test('routes rows with insufficient data to review, never a guessed decision', () => {
+  const r = run();
+  const noTraffic = byUrl(r, 'https://acme.example/reports/quarterly');
+  assert.equal(noTraffic.decision, 'review');
+  assert.match(noTraffic.reasons.join(' '), /pageviews/);
+
+  const noDate = byUrl(r, 'https://acme.example/orphan');
+  assert.equal(noDate.decision, 'review');
+  assert.equal(noDate.confidence, 'low');
+});
+
+test('decision counts match the seeded fixture exactly', () => {
+  const r = run();
+  assert.deepEqual(r.counts, { total: 12, keep: 5, update: 3, retire: 2, review: 2 });
+});
+
+test('flags the seeded metadata gaps (missing desc, short/long title, long desc)', () => {
+  const r = run();
+  const gapFor = (url, field) =>
+    r.metadataGaps.find((g) => g.url === url && g.field === field);
+
+  // tags/misc has an empty meta description
+  assert.ok(gapFor('https://acme.example/tags/misc', 'metaDescription'));
+  // jane-doe bio: title too short AND meta description missing (tier-1 page)
+  const jane = byUrl(r, 'https://acme.example/team/jane-doe');
+  assert.ok(jane.metadataGaps.some((g) => g.field === 'title' && /too short/.test(g.issue)));
+  assert.ok(jane.metadataGaps.some((g) => g.field === 'metaDescription' && g.issue === 'missing'));
+  // pricing-guide meta description exceeds 160 chars
+  const pricing = byUrl(r, 'https://acme.example/pricing-guide');
+  assert.ok(pricing.metadataGaps.some((g) => g.field === 'metaDescription' && /too long/.test(g.issue)));
+  // reference doc title exceeds 65 chars
+  const ref = byUrl(r, 'https://acme.example/docs/reference');
+  assert.ok(ref.metadataGaps.some((g) => g.field === 'title' && /too long/.test(g.issue)));
+});
+
+test('a missing date is a blocking (fail) gap', () => {
+  const r = run();
+  const orphan = byUrl(r, 'https://acme.example/orphan');
+  assert.ok(orphan.metadataGaps.some((g) => g.field === 'date' && g.severity === 'fail'));
+  assert.ok(r.migrationReadiness.blockingGaps >= 1);
+});
+
+test('detects duplicate titles across URLs (taxonomy collision)', () => {
+  const r = run();
+  const dup = r.duplicates.titles.find((d) => d.title === 'complete guide');
+  assert.ok(dup, 'the two "Complete Guide" pages are flagged');
+  assert.equal(dup.count, 2);
+});
+
+test('surfaces source fields with no canonical destination', () => {
+  const r = run();
+  assert.ok(r.unmappedFields.includes('author'), '"author" has no mapped destination');
+});
+
+test('migration readiness: redirect ledger, blockers, and a bounded score', () => {
+  const r = run();
+  const m = r.migrationReadiness;
+  assert.equal(m.redirectsRequired, 2);
+  assert.equal(m.redirectLedger.length, 2);
+  assert.ok(m.redirectLedger.every((e) => e.to === null && e.resolved === false && e.status === 301));
+  assert.ok(m.blockers.some((b) => /redirect target/.test(b)));
+  assert.ok(m.readinessScore >= 0 && m.readinessScore <= 100);
+  assert.equal(typeof m.fieldCoverage.pageviews.pct, 'number');
+});
+
+test('same input -> byte-identical output (deterministic, no wall clock)', () => {
+  const a = run();
+  const b = run();
+  assert.equal(JSON.stringify(a), JSON.stringify(b));
+});
+
+test('default asOf is the latest date in the export, not Date.now()', () => {
+  const r = inventoryFromText(csvText, 'csv'); // no asOf passed
+  assert.equal(r.asOf, '2026-06-20', 'latest last-updated in the CSV drives asOf');
+  // and it is still deterministic across runs
+  const r2 = inventoryFromText(csvText, 'csv');
+  assert.equal(JSON.stringify(r), JSON.stringify(r2));
+});
+
+test('JSON export path works and applies the same decision logic', () => {
+  const r = inventoryFromText(jsonText, 'json');
+  assert.equal(byUrl(r, 'https://acme.example/legacy-faq').decision, 'retire');
+  assert.equal(byUrl(r, 'https://acme.example/flagship').decision, 'update');
+  assert.equal(byUrl(r, 'https://acme.example/whats-new').decision, 'keep');
+});
+
+test('empty export yields a well-formed, non-crashing result', () => {
+  const r = buildInventory([]);
+  assert.equal(r.counts.total, 0);
+  assert.equal(r.migrationReadiness.readinessScore, 0);
+  assert.ok(r.migrationReadiness.blockers.length > 0);
+});
+
+test('thresholds are overridable and change decisions predictably', () => {
+  // Baseline: /guide is mid-traffic (300 views) and fresh (122 days) -> keep.
+  const base = run();
+  assert.equal(base.items.find((it) => it.url === 'https://acme.example/guide').decision, 'keep');
+  // Tighten veryStaleDays below 122: the same page now reads as decayed -> update.
+  const strict = inventoryFromText(csvText, 'csv', {
+    asOf: ASOF,
+    thresholds: { ...DEFAULT_THRESHOLDS, veryStaleDays: 100 },
+  });
+  const guide = strict.items.find((it) => it.url === 'https://acme.example/guide');
+  assert.equal(guide.decision, 'update');
+});

package/agent-cores/meta-ads/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@agent-cores/meta-ads",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Meta (Facebook/Instagram) ads auditor. Deterministic: parse an Ads Manager export, compute a ranked PROPOSE-ONLY change sheet (pause wasted spend, creative fatigue, low ROAS, cost-per-result inefficiency). No LLM in the core.",
+  "bin": {
+    "meta-ads": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

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

@@ -0,0 +1,166 @@
+// Deterministic Meta (Facebook/Instagram) ads analysis. No LLM. PROPOSE-ONLY.
+//
+// Input: parsed rows (canonical fields from parse.mjs), one per breakdown entity — an
+// ad, an ad set, or a campaign. 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.
+//
+// Four finding families, mirroring the Meta buyer's job:
+//   pause       — spend with zero results (burning budget, nothing back)
+//   low-roas    — purchases tracked but ROAS < 1 (losing money on every dollar)
+//   inefficient — cost per result far above the account average (expensive but not losing)
+//   fatigue     — high frequency (the same people seeing it too often — refresh creative)
+
+export const DEFAULT_THRESHOLDS = {
+  pauseMinSpend: 20,      // spend where "0 results" is signal, not noise
+  lowRoasMax: 1,          // ROAS < 1 loses money
+  lowRoasMinSpend: 30,
+  effCprMultiple: 3,      // cost/result >= 3x the account average
+  effMinSpend: 30,
+  fatigueFrequency: 3.5,  // avg impressions per person before fatigue bites
+  fatigueMinSpend: 20,
+};
+
+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;
+}
+// Name an entity by its most granular identifier, and say which level that is.
+function label(r) {
+  if (r.ad) return { name: r.ad, level: 'ad' };
+  if (r.adset) return { name: r.adset, level: 'ad set' };
+  return { name: r.campaign || '(unnamed)', level: 'campaign' };
+}
+function where(r) {
+  return [r.campaign, r.adset, r.ad].filter(Boolean).join(' / ') || 'account';
+}
+
+export function analyze(input, options = {}) {
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...(options.thresholds || {}) };
+  const rows = Array.isArray(input) ? input : (Array.isArray(input?.rows) ? input.rows : []);
+
+  const totalSpend = sum(rows, (r) => r.spend);
+  const totalResults = sum(rows, (r) => r.results);
+  const totalValue = sum(rows, (r) => r.purchaseValue ?? (Number.isFinite(r.roas) && Number.isFinite(r.spend) ? r.roas * r.spend : 0));
+  const accountCPR = totalResults > 0 ? totalSpend / totalResults : null;
+  const accountROAS = totalSpend > 0 && totalValue > 0 ? totalValue / totalSpend : null;
+
+  const changes = [];
+
+  for (const r of rows) {
+    const spend = r.spend || 0;
+    const results = r.results || 0;
+    const roas = Number.isFinite(r.roas) ? r.roas : null;
+    const cpr = Number.isFinite(r.costPerResult) ? r.costPerResult : (results > 0 ? spend / results : null);
+    const { name, level } = label(r);
+
+    // 1. pause — spend, zero results
+    if (results === 0 && spend >= thresholds.pauseMinSpend) {
+      changes.push({
+        type: 'pause',
+        change: `Pause ${level} "${name}" — spend with zero results`,
+        where: where(r),
+        why: `$${round(spend)} spent, 0 results${r.linkClicks ? `, ${r.linkClicks} link clicks that never converted` : ''}`,
+        expectedEffect: `Recover ~$${round(spend)}/period of wasted spend`,
+        risk: 'If this is a new ad still in learning, give it a few days of results before killing it.',
+        dollars: round(spend),
+        evidence: { entity: name, level, spend: round(spend), results: 0, roas },
+      });
+      continue; // one primary call per entity
+    }
+
+    // 2. low ROAS — losing money on tracked purchases
+    if (roas != null && roas < thresholds.lowRoasMax && spend >= thresholds.lowRoasMinSpend) {
+      const value = round(spend * roas);
+      const loss = round(spend - value);
+      changes.push({
+        type: 'low-roas',
+        change: `Pause or rework ${level} "${name}" — ROAS ${round(roas, 2)} is below break-even`,
+        where: where(r),
+        why: `$${round(spend)} spent returned ~$${value} (ROAS ${round(roas, 2)}) — losing ~$${loss}`,
+        expectedEffect: `Stop ~$${loss}/period of net loss; reallocate to profitable ad sets`,
+        risk: 'ROAS can lag with a long purchase window; confirm the attribution window before pausing a recent ad.',
+        dollars: loss,
+        evidence: { entity: name, level, spend: round(spend), roas: round(roas, 2), value },
+      });
+      continue;
+    }
+
+    // 3. inefficient — cost per result far above account average (and not already low-roas)
+    if (accountCPR != null && cpr != null && results > 0 && spend >= thresholds.effMinSpend
+      && cpr >= thresholds.effCprMultiple * accountCPR) {
+      const overspend = round(spend - results * accountCPR);
+      changes.push({
+        type: 'inefficient',
+        change: `Reduce or restructure ${level} "${name}" — cost per result far above account average`,
+        where: where(r),
+        why: `$${round(cpr)}/result vs $${round(accountCPR)} account average (${round(cpr / accountCPR, 1)}x) on $${round(spend)} spend`,
+        expectedEffect: `Recover ~$${overspend}/period of over-average cost`,
+        risk: 'A small results count makes cost-per-result noisy; check it holds over more conversions before cutting.',
+        dollars: overspend,
+        evidence: { entity: name, level, spend: round(spend), costPerResult: round(cpr), accountCPR: round(accountCPR), results },
+      });
+      continue;
+    }
+
+    // 4. fatigue — high frequency (creative refresh). Not a "continue" gate: a healthy ad
+    // can still be fatiguing, but pause/low-roas/inefficient are more urgent when present.
+    if (Number.isFinite(r.frequency) && r.frequency >= thresholds.fatigueFrequency && spend >= thresholds.fatigueMinSpend) {
+      changes.push({
+        type: 'fatigue',
+        change: `Refresh creative on ${level} "${name}" — audience is seeing it too often`,
+        where: where(r),
+        why: `frequency ${round(r.frequency, 1)} (each person saw it ~${Math.round(r.frequency)}x) on $${round(spend)} spend`,
+        expectedEffect: 'New creative usually recovers CTR/CPM as fatigue resets; expand or refresh the audience too',
+        risk: 'High frequency on a small retargeting pool can be fine; judge against that audience size.',
+        dollars: round(spend * 0.25), // a quarter of spend treated as at-risk to fatigue, for ranking
+        evidence: { entity: name, level, frequency: round(r.frequency, 1), spend: round(spend) },
+      });
+    }
+  }
+
+  // rank by dollars; tiebreak by type order then a stable key
+  const typeRank = { pause: 0, 'low-roas': 1, inefficient: 2, fatigue: 3 };
+  const keyed = changes.map((c, i) => ({ ...c, _i: i }));
+  keyed.sort((a, b) => {
+    if ((b.dollars || 0) !== (a.dollars || 0)) return (b.dollars || 0) - (a.dollars || 0);
+    if (typeRank[a.type] !== typeRank[b.type]) return typeRank[a.type] - typeRank[b.type];
+    return a._i - b._i;
+  });
+  const ranked = keyed.map(({ _i, ...c }, idx) => ({ rank: idx + 1, ...c }));
+
+  const recoverable = round(sum(ranked.filter((c) => c.type === 'pause' || c.type === 'low-roas' || c.type === 'inefficient'), (c) => c.dollars), 2);
+
+  return {
+    proposeOnly: true,
+    account: {
+      rows: rows.length,
+      totalSpend: round(totalSpend),
+      totalResults: round(totalResults, 1),
+      accountCostPerResult: accountCPR == null ? null : round(accountCPR),
+      accountROAS: accountROAS == null ? null : round(accountROAS, 2),
+    },
+    counts: {
+      total: ranked.length,
+      pause: ranked.filter((c) => c.type === 'pause').length,
+      lowRoas: ranked.filter((c) => c.type === 'low-roas').length,
+      inefficient: ranked.filter((c) => c.type === 'inefficient').length,
+      fatigue: ranked.filter((c) => c.type === 'fatigue').length,
+    },
+    wastedSpendRecoverable: recoverable,
+    summary: buildSummary(ranked, recoverable),
+    changes: ranked,
+  };
+}
+
+function buildSummary(ranked, recoverable) {
+  if (ranked.length === 0) return 'No pause, ROAS, cost, or fatigue changes found in the exported report.';
+  return `${ranked.length} proposed change(s); ~$${recoverable} recoverable from wasted/losing/over-cost spend. `
+    + `Start with: ${ranked[0].change}.`;
+}

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Real CLI. Reads a Meta Ads Manager export (CSV or JSON) from a file path, prints the
+// PROPOSE-ONLY change sheet as JSON on stdout and a one-line summary on stderr. No
+// account access.
+//   meta-ads <export.csv> [--pretty]
+//   meta-ads <export.json>          (a JSON array of rows, or { "rows": [...] })
+
+import { readFileSync } from 'node:fs';
+import { analyze } from './analyze.mjs';
+import { parseReport } from './parse.mjs';
+
+function main() {
+  const argv = process.argv.slice(2);
+  const pretty = argv.includes('--pretty');
+  const file = argv.find((a) => !a.startsWith('--'));
+  if (!file) {
+    console.error('Usage: meta-ads <export.csv|export.json> [--pretty]');
+    process.exitCode = 1;
+    return;
+  }
+  const text = readFileSync(file, 'utf8');
+  let rows;
+  if (file.endsWith('.json')) {
+    const parsed = JSON.parse(text);
+    rows = Array.isArray(parsed) ? parsed : (parsed.rows || []);
+  } else {
+    rows = parseReport(text);
+  }
+  const result = analyze(rows);
+  console.error(`meta-ads: ${result.summary}`);
+  console.log(JSON.stringify(result, null, pretty ? 2 : 0));
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+}