weftens 0.0.1 → 0.1.1

package/README.md

@@ -1,12 +1,178 @@
-# Weftens
-
-**Placeholder release.** This version reserves the package name. It contains no code and does nothing
-if installed — the working release follows.
-
-Weftens is one front door for marketing and representation work: you say what you need in plain
-language, it routes the request to the right agent and runs it on **your own AI subscription** — no
-account, no billing, no API key. Several of its agents need no model at all: the ad and SEO auditors
-are deterministic, run on your exported reports, and propose changes a human applies. They never write
-to a live account.
-
-MIT licensed. Free to use, including commercially.
+# Weftens
+
+**Where did the ad money go, and what should change?** Give Weftens an exported report from
+Google Ads, Meta, Amazon, or an SEO crawl, and it gives you back a ranked change sheet — each
+recommendation with where it applies, why it's proposed, what it's worth, and what could go
+wrong if you're wrong.
+
+    4 proposed changes  |  $604.27 of spend flagged
+    account: spend $910.00, 208 clicks, 11 conversions, CPA $82.73
+
+    1. Bid down or restrict "premium widget wholesale bulk"   $417.27
+       where  campaign: Brand / Brand - Exact
+       why    CPA $500 vs account $82.73 (6x); $500 for 1 conv
+       risk   Converting term — restricting too hard can cut real volume; prefer a bid cut first.
+
+    2. Add "free blue widgets" as a negative keyword   $90.00
+       where  campaign: Generic / Widgets - Broad
+       why    60 clicks, $90 spent, 0 conversions (expected ~3.2 at the 5.3% account rate)
+       risk   If the query is actually relevant, you forfeit those impressions.
+
+    Proposals only — nothing was sent to your ad account. Apply what you agree with.
+
+That is the actual output of the sample export included in this repo, produced by:
+
+    npm i weftens
+    npx weftens send paid-search audit --input agent-cores/paid-search/test/fixtures/search-terms.csv
+
+**Same file in, same change sheet out, every time.** The ad and SEO auditors are arithmetic, not
+a model — nothing is generated, so nothing can be invented, and two runs can be diffed to prove
+nothing moved. They read a file you already have and **never sign in to your ad account**. Note
+the second line of the first recommendation: that keyword *converted*. "Flagged" means the numbers
+crossed a threshold, not that the money is guaranteed back — the risk line is there because the
+call is still yours.
+
+**Not technical?** You don't have to run this. Send the repo link and your exported report to
+whoever manages your ads, or paste this to an AI assistant that can use your computer
+(Claude, ChatGPT/Codex, Gemini): *"install weftens and run the paid-search audit on my export."*
+
+## What's finished, and what isn't
+
+- **Finished and deterministic — seven auditors:** paid search (Google Ads), paid social (Meta),
+  Amazon PPC, technical SEO, content SEO, supply-path verification, content operations. No model,
+  no key, propose-only.
+- **Model-backed seats** run on an AI CLI *you* already have and are logged into — your
+  subscription, no API key, nobody is billed through Weftens. They are only as good as the model
+  you point them at. `claude` and `codex` are verified; `gemini` and `grok` are configured but have
+  never been run.
+- **Two seats are not in this repo.** `richy` (representation) and `pio` (prospect research) are
+  clients for separate services that aren't open source. Without those services configured they
+  return sample data that says so in its own output.
+- **The content pipeline is a placeholder.** Ten seats exist; it emits stub output and does not yet
+  take a free-text brief.
+
+Free, MIT licensed, no account, no billing.
+
+## Install
+
+```
+git clone git@github.com:Weftens/weftens.git
+cd weftens
+npm install
+npm test
+```
+
+That's the whole install. Everything lives in this one repo — the deterministic auditors
+(`agent-cores/`), the agent seat definitions (`agents/`), and the content pipeline (`content-org/`).
+A fresh clone runs on its own; there is no second checkout and no external directory. (Verified by
+cloning to an unrelated path and running the suite there — the earlier version of this claim was
+false: the end-to-end test resolved `agent-cores/` from the repo's *parent*, so it only passed on the
+author's machine.)
+
+Node 22+. `npm test` runs both suites: `test:unit` (vitest, the router/registry/CLI layer) and
+`test:cores` (`node --test`, the deterministic auditors — they are zero-install by design so a single
+core can be handed to someone who has nothing but Node).
+
+For the model-backed agents, have a model CLI installed and logged in (e.g. `claude`) — that's your
+own subscription, no key. The deterministic ad/SEO auditors need no model at all.
+
+## Use it as an SDK
+
+```js
+import { weftens, route, invoke, REGISTRY } from "weftens";
+
+// one call — route a request and run the chosen agent:
+const { decision, outcome } = await weftens("audit our facebook ads", { inputFile: "meta.csv" });
+console.log(decision.agent.name, outcome.result);
+
+// or drive the pieces yourself:
+const d = route({ text: "who are the funders for this grant" });
+const o = await invoke(d.agent, { text: "..." });
+```
+
+## Run
+
+```
+node bin/weftens.js list                      # the agent directory + which have a deterministic core
+node bin/weftens.js --route "<request>"        # dry run: which agent it routes to, and the words it matched
+node bin/weftens.js send "<request>"           # route, then run
+node bin/weftens.js send <agent> "<request>"   # address one agent directly
+node bin/weftens.js send <agent> --input report.csv          # feed a file to a calculator agent
+node bin/weftens.js send <agent> "<...>" --provider gemini   # pick which model runs it
+```
+
+Examples:
+
+```
+# paid media — PROPOSE-ONLY, never touches an account:
+node bin/weftens.js send paid-search x --input google-ads-export.csv
+node bin/weftens.js send meta-ads    x --input meta-ads-export.csv
+node bin/weftens.js send amazon-ppc  x --input amazon-search-terms.csv
+
+# a judgment call, run on your own model:
+node bin/weftens.js send hilbert "will this tagline survive being repeated: ..."
+```
+
+## What's inside
+
+- **Deterministic auditors** (no model; run on an exported report; propose changes a human applies):
+  `paid-search` (Google Ads), `meta-ads` (Facebook/Instagram), `amazon-ppc`, `seo-technical`,
+  `seo-content`, `supply-verify`, `content-ops`.
+- **Model-backed seats** (run on your AI CLI): the evaluation and marketing agents — `hilbert`,
+  `lippmann`, `agent2060`, `growth-marketing`, `social-voice`, `claims-content`, `security-writer`.
+- **Content team**: the `content` lead runs the 10-seat media pipeline as one node.
+- **Richy + PIO**: representation and operations agents with their own orchestrator/synthesizer —
+  `node bin/weftens.js route request.json`, or `weftens ask` / `weftens chat` for a conversation.
+
+Routing is deterministic and explainable: a request matches an agent by its declared keywords, and the
+CLI prints which words matched, so you always see why a request went where it did.
+
+## Configuration
+
+- `WEFTENS_PROVIDER` — which model CLI to use (default `claude`).
+- `providers.json` (or `WEFTENS_PROVIDERS_FILE`) — map a provider name to its command, e.g.
+  `{ "providers": { "gemini": { "cmd": "gemini", "args": ["-p"] } } }`.
+- `WEFTENS_WORKSPACE` — where `agent-cores` / `content-org` live (default: this repo's parent dir).
+- `WEFTENS_AGENTS_DIR` — where the agent seat files live. Defaults to the copies bundled in this repo
+  (`agents/`), so a fresh clone runs self-contained; override to point at your own set.
+
+## Honest status
+
+- **Verified:** deterministic routing, all seven auditor cores end-to-end, both specialist legs
+  (Richy/PIO) through the door, and BYOM model-produce via `claude`. **171 tests pass — 67 unit/CLI
+  (vitest) + 104 core (`node --test`)**, confirmed in a fresh clone at an unrelated path, not just in
+  the author's workspace.
+- **Richy and PIO are interfaces here, not implementations — read this before you install.**
+  Two of the seats (`richy`, representation intelligence; `pio`, prospect research and grants) are
+  clients for **separate services that are not part of this repo and are not open source**. What ships
+  here is the seat definition, the wire client, the orchestrator that joins their answers, and
+  fixtures. Point `WEFTENS_RICHY_URL`/`WEFTENS_RICHY_KEY` and the `WEFTENS_PIO_*` group at running
+  services and they work. Without those, they return **sample data that labels itself as sample data**
+  (`"sample": true`, and the headline says so) — so you can see the shape of the output, and you can
+  never mistake it for a finding about a real business. Everything else in this repo — all seven
+  deterministic auditors, the router, the CLI, the SDK — runs entirely on what you just cloned.
+  `weftens send richy --org "Acme Co" "audit our listings"` shows you exactly this.
+- **The router refuses rather than guesses.** Generic words alone ("site", "listing", "people") no
+  longer dispatch — a confident wrong route in front of a customer costs more than a reprompt.
+- **Licensed MIT.** Free to use, including commercially.
+- **Published:** `npm i weftens` installs the real thing (`weftens@0.1.0`, MIT). Verified from the
+  registry by a clean third-party install — `npx weftens list` prints the registry, and a
+  deterministic core runs a real audit from inside `node_modules`. (`0.0.1` was an empty name-holder;
+  ignore it.)
+- **Two providers verified, not one:** `claude` and `codex` both produce end-to-end through the
+  user's own subscription (codex confirmed 2026-07-19). `gemini` and `grok` remain config-only — the
+  shape is right, but neither CLI is installed here, so neither has been run. A missing or broken
+  provider degrades to a plain note; it never fabricates an answer.
+- **Dry-run only:** the content pipeline produces placeholder output; real content generation is gated
+  on open decisions.
+- **Propose-only:** every ad/SEO core proposes changes and writes nothing to a live account.
+
+## Notes
+
+**Weftens is the company AND this front door — one thing, not two.** Richy and PIO are two of the
+agent seats behind it, not standalone products under a brand. Architecture and agent-wiring detail:
+[`ARCHITECTURE.md`](ARCHITECTURE.md).
+
+Invariants that must not break: each agent stays independently runnable; PIO's wire-shape
+(`grantengine_session` cookie, `x-grantengine-*` headers) is frozen; the privacy spine — sanitized
+exports, human review gates, receipts — is shared across every seat.

package/agent-cores/amazon-ppc/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/amazon-ppc",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Amazon PPC search-term optimizer. Deterministic: parse a search-term report + margin/target-ACOS, compute harvest→negate→promote→re-bid proposals. PROPOSE-ONLY. No LLM in the core.",
+  "bin": {
+    "amazon-ppc": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "ppc": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/agent-cores/amazon-ppc/src/cli.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Real CLI. Reads an Amazon search-term report (CSV/TSV/JSON) from a file path,
+// computes the PROPOSE-ONLY change sheet, prints JSON on stdout and a one-line
+// summary on stderr.
+//
+//   amazon-ppc <report.csv> --target-acos 25 --margin 35
+//   amazon-ppc <report.json> --low-inventory "Auto - Garlic" --pretty
+//
+// Flags:
+//   --target-acos <n>   target ACOS (percent or fraction)
+//   --margin <n>        product contribution margin (percent or fraction)
+//   --neg-clicks <n>    zero-order click threshold to negate (default 10)
+//   --neg-spend <n>     zero-order spend threshold to negate (default 5)
+//   --low-inventory <c> campaign to suppress scaling on (repeatable)
+//   --pretty            pretty-print JSON
+
+import { readFileSync } from 'node:fs';
+import { optimize } from './optimize.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [], lowInventory: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--target-acos') args.targetAcos = Number(argv[++i]);
+    else if (a === '--margin') args.margin = Number(argv[++i]);
+    else if (a === '--neg-clicks') args.negClickThreshold = Number(argv[++i]);
+    else if (a === '--neg-spend') args.negSpendThreshold = Number(argv[++i]);
+    else if (a === '--low-inventory') args.lowInventory.push(argv[++i]);
+    else if (a === '--pretty') args.pretty = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const file = args._[0];
+  if (!file) {
+    console.error('Usage: amazon-ppc <report.csv|.json> [--target-acos 25] [--margin 35] [--low-inventory "Campaign"] [--pretty]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const text = readFileSync(file, 'utf8');
+  const cfg = {};
+  if (args.targetAcos !== undefined) cfg.targetAcos = args.targetAcos;
+  if (args.margin !== undefined) cfg.margin = args.margin;
+  if (args.negClickThreshold !== undefined) cfg.negClickThreshold = args.negClickThreshold;
+  if (args.negSpendThreshold !== undefined) cfg.negSpendThreshold = args.negSpendThreshold;
+  if (args.lowInventory.length) cfg.lowInventoryCampaigns = args.lowInventory;
+
+  const result = optimize(text, cfg);
+
+  console.error(
+    `amazon-ppc: ${result.totals.terms} terms, $${result.totals.spend} spend, ` +
+    `ACOS ${result.totals.acos ?? 'n/a'}% (target ${result.config.targetAcos}%) — ${result.summary.headline}`
+  );
+  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;
+}

package/agent-cores/amazon-ppc/src/optimize.mjs

@@ -0,0 +1,272 @@
+// Deterministic Amazon PPC optimizer. No LLM. Given normalized search-term rows
+// and an economics config (target ACOS derived from product margin), compute the
+// harvest -> negate -> promote -> re-bid change sheet. PROPOSE-ONLY: every row is
+// a proposal a human applies in the account, with the numbers attached.
+//
+// The whole thing is arithmetic and thresholds. Same input -> same output.
+
+import { normalizeRows } from './parse.mjs';
+
+const round2 = (n) => Math.round((n + Number.EPSILON) * 100) / 100;
+const pct = (n) => round2(n * 100); // fraction -> percentage number
+
+// A value like 25 (percent) or 0.25 (fraction) -> fraction.
+function asFraction(v) {
+  if (v === undefined || v === null) return null;
+  const n = Number(v);
+  if (Number.isNaN(n)) return null;
+  return n > 1 ? n / 100 : n;
+}
+
+export const DEFAULTS = {
+  targetAcos: 0.25, // fraction; where a term's ACOS should land for profit
+  margin: null, // product contribution margin (fraction). Break-even ACOS = margin.
+  negClickThreshold: 10, // clicks with zero orders => repeat waste => negate
+  negSpendThreshold: 5, // OR spend (with zero orders) at/above this => negate
+  minPromoteOrders: 2, // orders needed to call a term a signal, not luck
+  minPromoteClicks: 10, // clicks needed before promotion is credible
+  minRebidClicks: 8, // clicks needed before we trust a re-bid
+  rebidDeadband: 0.1, // ignore bid changes smaller than +/-10%
+  maxRaise: 1.0, // cap a single-cycle bid increase to +100%
+  maxCut: 0.5, // cap a single-cycle bid decrease to -50%
+  promoteBidCap: 1.5, // starting exact bid capped to 1.5x current effective CPC
+  bidFloor: 0.02, // Amazon minimum bid
+  lowInventoryCampaigns: [], // campaigns near stock-out: suppress scaling proposals
+};
+
+function resolveConfig(cfg = {}) {
+  const out = { ...DEFAULTS, ...cfg };
+  out.margin = asFraction(cfg.margin ?? out.margin);
+  // If only margin is given, target sits below break-even for actual profit.
+  if (cfg.targetAcos === undefined && out.margin != null) {
+    out.targetAcos = round2(out.margin * 0.75);
+  } else {
+    out.targetAcos = asFraction(out.targetAcos) ?? DEFAULTS.targetAcos;
+  }
+  out.breakEvenAcos = out.margin; // may be null if margin unknown
+  const lc = new Set((out.lowInventoryCampaigns || []).map((s) => String(s).toLowerCase()));
+  out.isLowInventory = (campaign) => lc.has(String(campaign).toLowerCase());
+  return out;
+}
+
+function isExactMatch(row) {
+  return /exact/i.test(row.matchType) || /exact/i.test(row.campaign);
+}
+function isAuto(row) {
+  return /auto/i.test(row.matchType) || /auto/i.test(row.campaign) || row.matchType === '' || row.matchType === '-';
+}
+
+function termAcos(row) {
+  return row.sales > 0 ? row.spend / row.sales : Infinity;
+}
+
+// Effective per-click bid we observed. Prefer reported CPC, else spend/clicks.
+function effectiveCpc(row) {
+  if (row.cpc > 0) return row.cpc;
+  return row.clicks > 0 ? row.spend / row.clicks : 0;
+}
+
+// The bid at which, at this term's observed revenue-per-click, ACOS == target.
+// rev/click * targetAcos. This is the economic anchor for every bid decision.
+function idealBid(row, targetAcos) {
+  const rpc = row.clicks > 0 ? row.sales / row.clicks : 0;
+  return rpc * targetAcos;
+}
+
+export function optimize(input, cfg = {}) {
+  const config = resolveConfig(cfg);
+  const rows = Array.isArray(input) && typeof input[0] === 'object' && input[0]?.searchTerm !== undefined
+    ? input
+    : normalizeRows(input);
+
+  const negatives = [];
+  const promotions = [];
+  const rebids = [];
+  const held = [];
+
+  const totals = { terms: 0, impressions: 0, clicks: 0, spend: 0, sales: 0, orders: 0 };
+
+  for (const row of rows) {
+    totals.terms += 1;
+    totals.impressions += row.impressions;
+    totals.clicks += row.clicks;
+    totals.spend += round2(row.spend);
+    totals.sales += round2(row.sales);
+    totals.orders += row.orders;
+
+    const acos = termAcos(row);
+    const cpc = effectiveCpc(row);
+    const ideal = idealBid(row, config.targetAcos);
+    const lowInv = config.isLowInventory(row.campaign);
+
+    // 1. NEGATE — repeat waste: clicks/spend accrued, zero orders.
+    if (row.orders === 0 && (row.clicks >= config.negClickThreshold || row.spend >= config.negSpendThreshold)) {
+      negatives.push({
+        term: row.searchTerm,
+        campaign: row.campaign,
+        matchType: row.matchType || (isAuto(row) ? 'auto' : ''),
+        clicks: row.clicks,
+        spend: round2(row.spend),
+        orders: 0,
+        spendStopped: round2(row.spend),
+        reason: row.clicks >= config.negClickThreshold
+          ? `${row.clicks} clicks, 0 orders (>= ${config.negClickThreshold}-click waste bar)`
+          : `$${round2(row.spend)} spent, 0 orders (>= $${config.negSpendThreshold} waste bar)`,
+      });
+      continue;
+    }
+
+    // 2. PROMOTE — a converting non-exact winner isolated into its own exact campaign.
+    const meetsPromoteBar =
+      row.orders >= config.minPromoteOrders &&
+      row.clicks >= config.minPromoteClicks &&
+      acos <= config.targetAcos &&
+      !isExactMatch(row);
+
+    if (meetsPromoteBar) {
+      if (lowInv) {
+        held.push({
+          term: row.searchTerm,
+          campaign: row.campaign,
+          action: 'promote-suppressed',
+          reason: `winner (ACOS ${pct(acos)}%) but campaign flagged low inventory — do not scale into a stock-out`,
+        });
+        continue;
+      }
+      const rpc = row.sales / row.clicks;
+      const cap = cpc > 0 ? cpc * config.promoteBidCap : ideal;
+      const capped = ideal > cap;
+      const startingBid = Math.max(config.bidFloor, round2(capped ? cap : ideal));
+      promotions.push({
+        term: row.searchTerm,
+        sourceCampaign: row.campaign,
+        sourceMatchType: row.matchType || (isAuto(row) ? 'auto' : ''),
+        clicks: row.clicks,
+        orders: row.orders,
+        sales: round2(row.sales),
+        acos: pct(acos),
+        newCampaign: `Exact - ${row.searchTerm}`,
+        newMatchType: 'exact',
+        startingBid,
+        capped,
+        negateInSource: isAuto(row),
+        marginMath:
+          `${row.orders} orders / ${row.clicks} clicks, $${round2(row.sales)} sales -> ` +
+          `$${round2(rpc)} rev/click x ${pct(config.targetAcos)}% target ACOS = $${round2(ideal)} ideal bid` +
+          (capped ? `, capped to ${config.promoteBidCap}x CPC ($${round2(cpc)}) = $${startingBid}` : ` = $${startingBid}`),
+      });
+      continue;
+    }
+
+    // 3. RE-BID — converting term whose current CPC is off its economic ideal bid.
+    if (row.orders >= 1 && row.clicks >= config.minRebidClicks && cpc > 0 && ideal > 0) {
+      const rawRatio = ideal / cpc; // >1 underpaying (raise), <1 overpaying (cut)
+      const delta = Math.abs(rawRatio - 1);
+      if (delta >= config.rebidDeadband) {
+        const up = ideal > cpc;
+        if (up && lowInv) {
+          held.push({
+            term: row.searchTerm,
+            campaign: row.campaign,
+            action: 'raise-suppressed',
+            reason: `bid-up justified (ACOS ${pct(acos)}%) but campaign flagged low inventory — hold`,
+          });
+          continue;
+        }
+        let target = ideal;
+        let capped = false;
+        if (up) {
+          const ceiling = cpc * (1 + config.maxRaise);
+          if (target > ceiling) { target = ceiling; capped = true; }
+        } else {
+          const floorByCut = cpc * (1 - config.maxCut);
+          if (target < floorByCut) { target = floorByCut; capped = true; }
+        }
+        const newBid = Math.max(config.bidFloor, round2(target));
+        const oldBid = round2(cpc);
+        const overBreakEven = config.breakEvenAcos != null && acos > config.breakEvenAcos;
+        rebids.push({
+          term: row.searchTerm,
+          campaign: row.campaign,
+          matchType: row.matchType || (isExactMatch(row) ? 'exact' : ''),
+          clicks: row.clicks,
+          orders: row.orders,
+          acos: pct(acos),
+          currentCpc: oldBid,
+          oldBid,
+          newBid,
+          direction: up ? 'up' : 'down',
+          changePct: pct((newBid - oldBid) / oldBid),
+          capped,
+          why:
+            `ACOS ${pct(acos)}% vs ${pct(config.targetAcos)}% target; ideal bid $${round2(ideal)} ` +
+            `${up ? 'above' : 'below'} current $${oldBid} -> ${up ? 'raise' : 'cut'} to $${newBid}` +
+            (capped ? ` (capped at ${up ? '+' : '-'}${pct(up ? config.maxRaise : config.maxCut)}%)` : '') +
+            (overBreakEven ? ` [losing: ACOS above ${pct(config.breakEvenAcos)}% break-even]` : ''),
+        });
+        continue;
+      }
+    }
+
+    // Otherwise: hold. Not enough signal, or already on target.
+    held.push({
+      term: row.searchTerm,
+      campaign: row.campaign,
+      action: 'hold',
+      reason: row.orders === 0
+        ? `${row.clicks} clicks, 0 orders — below the ${config.negClickThreshold}-click / $${config.negSpendThreshold} negate bar (watch)`
+        : `on target or insufficient click signal (${row.clicks} clicks)`,
+    });
+  }
+
+  // Deterministic ordering: biggest lever first, term as stable tie-breaker.
+  negatives.sort((a, b) => b.spendStopped - a.spendStopped || a.term.localeCompare(b.term));
+  promotions.sort((a, b) => b.sales - a.sales || a.term.localeCompare(b.term));
+  rebids.sort((a, b) => Math.abs(b.changePct) - Math.abs(a.changePct) || a.term.localeCompare(b.term));
+  held.sort((a, b) => a.term.localeCompare(b.term));
+
+  const accountAcos = totals.sales > 0 ? totals.spend / totals.sales : Infinity;
+  const estSpendStopped = round2(negatives.reduce((s, n) => s + n.spendStopped, 0));
+
+  return {
+    config: {
+      targetAcos: pct(config.targetAcos),
+      margin: config.margin != null ? pct(config.margin) : null,
+      breakEvenAcos: config.breakEvenAcos != null ? pct(config.breakEvenAcos) : null,
+      negClickThreshold: config.negClickThreshold,
+      negSpendThreshold: config.negSpendThreshold,
+      minPromoteOrders: config.minPromoteOrders,
+      minPromoteClicks: config.minPromoteClicks,
+      lowInventoryCampaigns: config.lowInventoryCampaigns,
+    },
+    totals: {
+      ...totals,
+      spend: round2(totals.spend),
+      sales: round2(totals.sales),
+      acos: totals.sales > 0 ? pct(accountAcos) : null,
+    },
+    summary: {
+      negatives: negatives.length,
+      estSpendStopped,
+      promotions: promotions.length,
+      rebids: rebids.length,
+      rebidsUp: rebids.filter((r) => r.direction === 'up').length,
+      rebidsDown: rebids.filter((r) => r.direction === 'down').length,
+      held: held.length,
+      headline: buildHeadline({ negatives, promotions, rebids, estSpendStopped }),
+    },
+    negatives,
+    promotions,
+    rebids,
+    held,
+  };
+}
+
+function buildHeadline({ negatives, promotions, rebids, estSpendStopped }) {
+  const parts = [];
+  if (negatives.length) parts.push(`${negatives.length} negatives (~$${estSpendStopped} waste stopped)`);
+  if (promotions.length) parts.push(`${promotions.length} winners to promote`);
+  if (rebids.length) parts.push(`${rebids.length} re-bids`);
+  if (parts.length === 0) return 'No proposed changes — every term is on target or below signal thresholds.';
+  return `PROPOSE-ONLY change sheet: ${parts.join(', ')}.`;
+}