@damiangilgonzalez/harness 1.3.7

package/skills/accessibility/references/wcag22-checklist.md

@@ -0,0 +1,83 @@
+# WCAG 2.2 Level AA checklist (grouped by POUR)
+
+The conformance bar. Each item is tagged how it's best verified:
+
+- **[auto]** — an engine (axe-core) catches it reliably.
+- **[manual]** — needs a human (keyboard, screen reader, judgement).
+- **[both]** — automation flags candidates, a human confirms intent.
+
+**NEW** marks a criterion introduced in WCAG 2.2 (W3C Recommendation 2023-10-05). WCAG 2.2 added 9 criteria and **removed 4.1.1 Parsing** — don't chase it anymore.
+
+This is the AA conformance set (A + AA). Numbers (`x.y.z`) are the official SC ids so you can cross-reference the spec.
+
+---
+
+## Perceivable
+
+- **1.1.1 Non-text Content (A)** — every image/icon/control has a text alternative; decorative images use `alt=""`. **[both]** (axe flags missing alt; a human judges whether it's *meaningful*).
+- **1.3.1 Info and Relationships (A)** — structure is in the markup: headings, lists, `<label for>`, `<th scope>`, fieldset/legend. **[both]**
+- **1.3.2 Meaningful Sequence (A)** — DOM order matches reading order; don't reorder with CSS in a way that breaks it. **[manual]**
+- **1.3.4 Orientation (AA)** — don't lock to portrait/landscape unless essential. **[manual]**
+- **1.3.5 Identify Input Purpose (AA)** — use `autocomplete` tokens on personal-data fields (`name`, `email`, `tel`). **[auto]**
+- **1.4.1 Use of Color (A)** — color is never the only way to convey info; pair with text/icon/shape. **[manual]**
+- **1.4.3 Contrast (Minimum) (AA)** — text **4.5:1**; large text (≥24px or ≥18.66px bold) **3:1**. **[auto in a real browser; jsdom can't]**
+- **1.4.4 Resize Text (AA)** — text scales to 200% with no loss of content/function. **[manual]**
+- **1.4.5 Images of Text (AA)** — use real text, not pictures of text, except logos. **[manual]**
+- **1.4.10 Reflow (AA)** — content reflows to a 320px-wide viewport with no 2-D scrolling. **[manual]**
+- **1.4.11 Non-text Contrast (AA)** — UI components and meaningful graphics hit **3:1** (input borders, focus indicators, icon glyphs, chart segments). **[both]**
+- **1.4.12 Text Spacing (AA)** — no content clipped when users override line/letter/word spacing. **[manual]**
+- **1.4.13 Content on Hover or Focus (AA)** — hover/focus popups are dismissable, hoverable, and persistent. **[manual]**
+
+## Operable
+
+- **2.1.1 Keyboard (A)** — all functionality available from the keyboard. **[manual]**
+- **2.1.2 No Keyboard Trap (A)** — focus can always move away with the keyboard. **[manual]**
+- **2.1.4 Character Key Shortcuts (A)** — single-key shortcuts can be turned off/remapped or only fire on focus. **[manual]**
+- **2.4.1 Bypass Blocks (A)** — a skip link or landmarks let users bypass repeated content. **[both]**
+- **2.4.2 Page Titled (A)** — every page has a unique, descriptive `<title>`. **[auto]**
+- **2.4.3 Focus Order (A)** — focus order preserves meaning and operability. **[manual]**
+- **2.4.4 Link Purpose (In Context) (A)** — link text says where it goes; no bare "click here". **[both]**
+- **2.4.5 Multiple Ways (AA)** — more than one way to find a page (nav, search, sitemap). **[manual]**
+- **2.4.6 Headings and Labels (AA)** — headings and labels describe topic/purpose. **[manual]**
+- **2.4.7 Focus Visible (AA)** — keyboard focus is always visibly indicated. **[both]**
+- **2.4.11 Focus Not Obscured (Minimum) (AA)** — **NEW** — a focused element isn't entirely hidden by sticky headers/footers/cookie bars. **[manual]**
+- **2.5.1 Pointer Gestures (A)** — multipoint/path gestures have a single-pointer alternative. **[manual]**
+- **2.5.2 Pointer Cancellation (A)** — actions fire on up-event, allow abort. **[manual]**
+- **2.5.3 Label in Name (A)** — the accessible name contains the visible label text. **[both]**
+- **2.5.4 Motion Actuation (A)** — device-motion features have a UI alternative and can be disabled. **[manual]**
+- **2.5.7 Dragging Movements (AA)** — **NEW** — anything by dragging has a single-pointer (tap/button) alternative. **[manual]**
+- **2.5.8 Target Size (Minimum) (AA)** — **NEW** — interactive targets ≥ **24×24 CSS px**, or spaced so a 24px circle doesn't overlap neighbors (spacing exception). **[both]**
+- **2.3.1 Three Flashes or Below (A)** — nothing flashes more than 3×/second. **[manual]**
+
+## Understandable
+
+- **3.1.1 Language of Page (A)** — `<html lang="…">` set. **[auto]**
+- **3.1.2 Language of Parts (AA)** — inline language changes marked with `lang`. **[manual]**
+- **3.2.1 On Focus (A)** — focus alone doesn't trigger a context change. **[manual]**
+- **3.2.2 On Input (A)** — changing a setting doesn't auto-change context without warning. **[manual]**
+- **3.2.3 Consistent Navigation (AA)** — repeated nav stays in the same relative order. **[manual]**
+- **3.2.4 Consistent Identification (AA)** — same-function components are labeled consistently. **[manual]**
+- **3.2.6 Consistent Help (A)** — **NEW** — help (contact, FAQ link, chat) appears in the same relative order across pages. **[manual]**
+- **3.3.1 Error Identification (A)** — errors are identified in text and described. **[both]**
+- **3.3.2 Labels or Instructions (A)** — inputs have labels/instructions. **[both]**
+- **3.3.3 Error Suggestion (AA)** — when known, suggest a correction. **[manual]**
+- **3.3.4 Error Prevention (Legal/Financial/Data) (AA)** — reversible/checked/confirmed submissions. **[manual]**
+- **3.3.7 Redundant Entry (A)** — **NEW** — don't ask for info already provided in the same process; auto-populate or let them select it. **[manual]**
+- **3.3.8 Accessible Authentication (Minimum) (AA)** — **NEW** — no cognitive-function test to authenticate (no puzzles, no transcription); allow paste and password managers. **[manual]**
+
+## Robust
+
+- **4.1.2 Name, Role, Value (A)** — every UI component exposes a correct name, role, and current state/value to assistive tech. **[both]**
+- **4.1.3 Status Messages (AA)** — status updates are announced without moving focus (live regions / roles). **[both]**
+
+> 4.1.1 Parsing was **removed** in WCAG 2.2. Modern browsers recover from minor markup errors; the criterion no longer applies.
+
+---
+
+## How to work this list
+
+1. Run axe (browser, `wcag22aa` tag) — clears most **[auto]** rows.
+2. Do a keyboard-only pass — clears the operable **[manual]** rows.
+3. One screen-reader spot check — names/roles/state, live-region announcements (4.1.2, 4.1.3).
+4. Zoom 200% + 320px reflow — 1.4.4 / 1.4.10.
+5. Manually verify the 2.2 NEW rows; they're almost all **[manual]** and the ones most teams miss.

package/skills/accessibility/scripts/verify.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# verify.sh — accessibility conformance check (read-only by default).
+#
+# Detects the project's a11y tooling and runs the cheapest verdict it can:
+#   1. an explicit a11y test script in package.json (e.g. "test:a11y")
+#   2. @axe-core/playwright  -> needs a URL; runs an inline scan only if A11Y_URL is set
+#   3. jest-axe              -> runs the project's jest tests
+#   4. eslint-plugin-jsx-a11y -> lints src and counts jsx-a11y violations
+#   5. nothing installed     -> prints install hints and EXITS 0 (skip, never a false failure)
+#
+# Exits non-zero ONLY when serious/critical violations are found.
+# Usage: verify.sh [target-dir]   (default: current directory)
+set -euo pipefail
+
+TARGET="${1:-.}"
+cd "$TARGET"
+
+say() { printf '%s\n' "$*"; }
+
+if [ ! -f package.json ]; then
+  say "a11y: no package.json in '$TARGET' — nothing to verify. (skip)"
+  exit 0
+fi
+
+# read a top-level field out of package.json without extra tooling
+pkg_has() { node -e "const p=require('./package.json');const d={...p.dependencies,...p.devDependencies};process.exit(d['$1']?0:1)" 2>/dev/null; }
+script_has() { node -e "const p=require('./package.json');process.exit((p.scripts||{})['$1']?0:1)" 2>/dev/null; }
+
+PM="npm"
+if [ -f pnpm-lock.yaml ]; then PM="pnpm"; elif [ -f yarn.lock ]; then PM="yarn"; fi
+run_script() { case "$PM" in pnpm) pnpm run "$1";; yarn) yarn "$1";; *) npm run "$1";; esac; }
+
+# 1) explicit a11y script wins
+for s in test:a11y a11y test:accessibility accessibility; do
+  if script_has "$s"; then
+    say "a11y: running '$s' via $PM"
+    run_script "$s"
+    exit $?
+  fi
+done
+
+# 2) @axe-core/playwright — needs a live URL
+if pkg_has "@axe-core/playwright"; then
+  if [ -z "${A11Y_URL:-}" ]; then
+    say "a11y: @axe-core/playwright present but A11Y_URL not set."
+    say "      Set A11Y_URL=http://localhost:3000 (with the app running) to scan. (skip)"
+    exit 0
+  fi
+  say "a11y: scanning $A11Y_URL with @axe-core/playwright (wcag2a,wcag2aa,wcag22aa)"
+  node - "$A11Y_URL" <<'NODE'
+const { chromium } = require('playwright');
+const AxeBuilder = require('@axe-core/playwright').default;
+(async () => {
+  const url = process.argv[2];
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto(url, { waitUntil: 'load' });
+  const r = await new AxeBuilder({ page }).withTags(['wcag2a','wcag2aa','wcag22aa']).analyze();
+  await browser.close();
+  const by = {};
+  for (const v of r.violations) by[v.impact || 'unknown'] = (by[v.impact || 'unknown'] || 0) + 1;
+  console.log('a11y: violations by impact ' + (JSON.stringify(by) || '{}'));
+  const blocking = (by.serious || 0) + (by.critical || 0);
+  if (blocking > 0) { console.error(`a11y: ${blocking} serious/critical violation(s) — FAIL`); process.exit(1); }
+  console.log('a11y: no serious/critical violations');
+})().catch(e => { console.error('a11y: scan error — ' + e.message + ' (skip)'); process.exit(0); });
+NODE
+  exit $?
+fi
+
+# 3) jest-axe — run jest if a test script exists
+if pkg_has "jest-axe"; then
+  if script_has "test"; then
+    say "a11y: jest-axe present — running '$PM test' (note: contrast disabled in jsdom)"
+    run_script test
+    exit $?
+  fi
+  say "a11y: jest-axe present but no 'test' script. (skip)"
+  exit 0
+fi
+
+# 4) eslint-plugin-jsx-a11y — lint and count
+if pkg_has "eslint-plugin-jsx-a11y"; then
+  SRC="src"; [ -d "$SRC" ] || SRC="."
+  say "a11y: linting $SRC with eslint (jsx-a11y rules)"
+  OUT="$(npx --no-install eslint "$SRC" --ext .js,.jsx,.ts,.tsx -f json 2>/dev/null || true)"
+  if [ -z "$OUT" ]; then
+    say "a11y: eslint produced no output (config or install issue). (skip)"
+    exit 0
+  fi
+  COUNT="$(printf '%s' "$OUT" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{const r=JSON.parse(s);let n=0;for(const f of r)for(const m of f.messages)if((m.ruleId||'').startsWith('jsx-a11y/'))n++;console.log(n)}catch{console.log(0)}})")"
+  say "a11y: jsx-a11y violations: $COUNT"
+  [ "$COUNT" -gt 0 ] && exit 1
+  exit 0
+fi
+
+# 5) nothing detected — guide, don't fail
+say "a11y: no a11y tooling detected. (skip)"
+say "      Install one of:"
+say "        npm i -D eslint-plugin-jsx-a11y   # static lint of JSX"
+say "        npm i -D jest-axe                 # unit-level axe (contrast off in jsdom)"
+say "        npm i -D @axe-core/playwright     # real-browser scan incl. contrast"
+exit 0

package/skills/ads/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: ads
+description: "Use when running or fixing paid acquisition on Google or Meta — campaign structure (Performance Max, Demand Gen, Search, Advantage+), platform-fit creative, budget/scaling rules, break-even ROAS math, and Consent Mode v2 / CAPI tracking gaps. NOT the page the ad clicks into (that is `landing-copy`), NOT the channel-mix plan (that is `marketing`)."
+tags: [paid-ads, google-ads, meta-ads, roas, performance-max, ppc, paid-acquisition]
+recommends: [marketing, landing-copy, brand-voice, ab-testing, analytics, dashboard, forecasting, lead-gen]
+origin: risco
+---
+
+# ads
+
+You are the paid-acquisition operator. You run money through Google and Meta to buy
+customers, and you answer four questions in this order: **structure → creative →
+budget → ROAS**. Your subject is the live account and its economics — the campaign
+shape, the asset sets, the bid/budget config, and the math that says *keep scaling*
+or *kill it*.
+
+The nearest miss is `marketing`: it decides *whether to run paid at all and the
+channel mix* (`../marketing/SKILL.md`); you execute *the Google/Meta buy inside that
+plan* down to asset groups, bids, and break-even ROAS.
+
+## ROAS first — it gates everything
+
+Do the money math before you touch a single campaign setting. Structure is
+meaningless if the unit economics don't close.
+
+- **Break-even ROAS = 1 ÷ gross-margin %.** 40% margin needs ≥**2.5x** to break even
+  on contribution; 50% margin needs ≥**2.0x**. *Why:* below this every conversion
+  loses money no matter how good the targeting.
+- **Target by stage.** Profit-mode brands aim **3.5x–5x on Meta**, **5x–8x on Google
+  Search**. Scaling-mode brands accept **2x–3x** and judge on blended MER, not
+  campaign ROAS. *Why:* you trade margin for growth deliberately, not by accident.
+- **Platform-reported ROAS lies.** It over-reports **30–100%** by double-counting
+  conversions across campaigns and surfaces; true incremental revenue is often only
+  **30–60%** of the platform number. *Why:* last-click attribution credits the ad for
+  sales that would have happened anyway.
+- **The truth check is incrementality, not the dashboard.** Geo-holdout / ghost-ad
+  tests are the 2026 gold standard; for the scaling decision switch to **blended MER**
+  (total revenue ÷ total ad spend). *Why:* it's the only number tied to your bank
+  account.
+
+```text
+Bad:  "We hit 4.2x ROAS — scale it!"        (platform, last-click)
+Good: "Platform 4.2x, geo-holdout incremental 2.1x, break-even 2.5x.
+       Incremental is BELOW break-even — we're losing money. Cut."
+```
+
+Full worked math, the platform-vs-MER-vs-incrementality table, a geo-holdout test
+design, and the scale/hold/kill rule live in `references/roas-model.md`.
+
+## Pick the surface
+
+Choose by goal, how much creative/audience control you need, and how much conversion
+data the account already produces. Don't default to the most-automated option just
+because it exists.
+
+| Platform | Surface | Use when |
+|---|---|---|
+| Google | **Performance Max** | Full-funnel, you'll cede control for reach, and the account already has steady conversion volume to feed the algorithm. |
+| Google | **Demand Gen** | You need creative + audience control PMax won't give: preview exact combinations, opt out of optimized targeting, report by placement/audience/asset. |
+| Google | **Search** | Capturing existing high-intent demand; keyword/query control matters more than discovery reach. |
+| Meta | **Advantage+ Shopping/Sales** | Acquiring new customers at volume, you can feed 15–20+ creatives, and the daily budget clears the learning floor. |
+| Meta | **Manual (ABO/CBO)** | Tight audience control, small budgets, or testing a specific segment the algorithm would dilute. |
+
+## Structure
+
+- **Consolidate to feed the learning phase.** A campaign needs enough conversions to
+  exit learning; many tiny campaigns each starve. *Why:* the algorithm can't optimize
+  on noise.
+- **Split budget by job:** broad/prospecting, a manual test slice, and retargeting —
+  not eight clones of the same campaign. *Why:* each slice answers a different
+  question.
+- **Cap existing customers on Advantage+ at 20–30%.** Without the cap, Meta defaults
+  to cheap retargeting conversions and you stop acquiring while the dashboard looks
+  great. *Why:* easy reconversions inflate ROAS and hide that growth stalled.
+- **Protect the learning phase: hold structure ≥4 weeks.** Budget changes >20%,
+  bid-strategy switches, or adding asset groups all **restart** learning. *Why:* every
+  reset throws away the data you paid to collect.
+
+```text
+Bad:  8 campaigns × $20/day, each restarted twice this week.
+Good: 1 prospecting campaign above the conversion-data floor, untouched 4 weeks,
+      then act on the data.
+```
+
+PMax allows max **25 asset groups** per campaign — start with **1–2**. Full structure
+detail and the Google Ads API version note for scripting are in
+`references/platform-specs.md`.
+
+## Creative
+
+Write the ad-surface copy only. It must obey the brand's voice (`../brand-voice/SKILL.md`)
+and click into a page you do not write (`../landing-copy/SKILL.md`).
+
+Per-surface caps (summary — full tables, image/video orientations and sizes, and the
+Low/Good/Best rotation playbook in `references/platform-specs.md`):
+
+| Surface | Headlines | Descriptions | Media |
+|---|---|---|---|
+| PMax (per asset group) | 15 × 30 char + 1 long × 90 char | 5 × 90 char | 20 images, 5 videos |
+| Demand Gen | 5 × 40 char | 5 × 90 char | per format |
+| Search (RSA) | 15 × 30 char | 4 × 90 char | — |
+| Meta Advantage+ | feed 15–20+ creative variations | — | mixed orientations |
+
+- **Feed 15–20+ variations on Advantage+.** With 3–5 creatives the algorithm can't
+  test and you've built an expensive manual campaign. *Why:* automation needs raw
+  material to compare.
+- **Refresh on cadence to fight fatigue.** Google rates each asset **Low / Good /
+  Best**; replace **Low** assets after **4–6 weeks**. *Why:* a dead creative drags the
+  whole asset group's rating and delivery.
+- **Never overflow a platform limit.** A 33-char "30-char" headline gets truncated or
+  rejected and tanks the asset rating. *Why:* the limit is hard, not advisory — lint
+  before you ship (see `scripts/verify.sh`).
+
+## Budget & scaling
+
+- **Meta Advantage+ floor ≈ 50× target CPA**, with a practical minimum around
+  **$100/day**; below ~$50/day the algorithm can't exit learning. *Why:* it needs
+  ~50 conversions/week to optimize.
+- **Scale ≤ 20% per week.** Bigger jumps reset the learning phase and you start over
+  at a worse CPA. *Why:* the algorithm re-explores after a large budget shock.
+
+```text
+target CPA $40  →  Advantage+ floor ≈ 50 × $40 = $2,000/day
+                   (or ramp in ≤20%/week steps to get there)
+```
+
+## Measurement setup gate
+
+Conversions you can't track don't count, and Smart Bidding degrades without them. Run
+this gate before judging any campaign:
+
+- [ ] **Consent Mode v2 (Advanced)** — mandatory for EEA/UK since 2024-03-06.
+- [ ] **Enhanced Conversions** on Google — hashed first-party email/phone to recover
+      modeled conversions.
+- [ ] **Meta CAPI** — the server-side equivalent; most stores need both it and
+      Enhanced Conversions.
+- [ ] Account updated for the unified `ad_storage` parameter before **2026-06-15** —
+      after that, un-updated accounts risk attribution gaps and bidding degradation.
+
+Hand the reporting/dashboards to the `analytics` / `dashboard` skills — you set up
+the signal; they build the read-out.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Scaling on platform ROAS | Over-reports 30–100% via double-counting | Validate with geo-holdout / blended MER first |
+| Fragmenting budget across many tiny campaigns | None gets enough data to exit learning | Consolidate above the conversion-data floor |
+| No existing-customer cap on Advantage+ | Meta drifts to cheap retargeting; acquisition stops | Cap existing customers at 20–30% |
+| Launching with 3–5 creatives | Algorithm can't test; it's a manual campaign in disguise | Feed 15–20+ variations, refresh weekly |
+| Tweaking budget/bids/assets every few days | Each >20% change resets the learning phase | Hold structure ≥4 weeks, then act on data |
+| Target ROAS set below break-even | Every conversion loses money | Set target ≥ 1÷margin; profit-mode 3.5x–8x |
+| Ignoring Consent Mode v2 / CAPI | Conversions go unattributed; Smart Bidding degrades | Advanced consent + Enhanced Conversions + CAPI |
+| Copy that overflows the platform char limit | Truncated/rejected assets, Low rating | Lint headlines/descriptions to per-surface caps |
+
+## Handoff
+
+- **Real experiment design** (sample size, significance) → the `ab-testing` skill.
+- **Blended/next-quarter revenue projection** → the `forecasting` skill.
+- **Top-of-funnel B2B prospect lists** (not paid media) → the `lead-gen` skill.

package/skills/ads/evals/README.md

@@ -0,0 +1,15 @@
+# Evals — ads
+
+`cases.yaml` has three blocks. **should_trigger** and **should_not_trigger** are
+routing checks: feed each `prompt` to the router and confirm it picks `ads` for the
+triggers (including the non-obvious "the bank account disagrees" finance-looking one
+and the Spanish/Catalan phrasings) and the named real sibling for each near-miss
+(`landing-copy`, `ab-testing`, `marketing`, `dashboard`, `brand-voice`). The
+near-miss cases pass only when the router prefers the named sibling over `ads`. The
+**capability** block is an LLM- or human-graded rubric: run the scenario with the
+skill loaded and check the produced launch plan hits every `must_include` line —
+break-even computed (2.0x), target ≥ break-even, ~50× CPA budget floor, the 20–30%
+existing-customer cap, 15–20+ in-spec creatives, the Consent Mode v2 / Enhanced
+Conversions / CAPI gate, incrementality/MER (not platform ROAS) as the kill switch,
+and the handoffs. There's no automated runner here — grade by reading the output
+against the list, or wire it into your eval harness of choice.

package/skills/ads/evals/cases.yaml

@@ -0,0 +1,58 @@
+skill: ads
+
+# Prompts that MUST load `ads`. The skill owns the paid-media BUY on Google and
+# Meta: campaign structure, platform-fit creative, budget/scaling, and the
+# break-even/incremental ROAS decision. It does NOT own the landing page
+# (landing-copy), the voice (brand-voice), the experiment stats (ab-testing), or
+# the channel-mix decision (marketing).
+should_trigger:
+  - prompt: "Set up our Google Ads from scratch for a DTC skincare brand."
+    why: "Standing up account structure (which campaign types, budget split, signal) is the skill's core job."
+
+  - prompt: "Our Performance Max campaign spends a fortune but barely converts — what's wrong with the structure?"
+    why: "Diagnosing and restructuring a PMax campaign (asset groups, learning phase, signal) is owned here."
+
+  - prompt: "Platform says 4.2x ROAS but the bank account disagrees — are we actually profitable?"
+    why: "Non-obvious: reads like a finance/bookkeeping question, but it's incrementality vs break-even ROAS on a paid buy — the skill's ROAS gate."
+
+  - prompt: "How much should each Meta campaign get per day, and how fast can I scale the winners?"
+    why: "Daily budget floors (50x CPA) and the <=20%/week scaling rule are the budget-and-scaling section, even though the skill is never named."
+
+  - prompt: "Qué ROAS necesito en Google Search para no perder dinero con un margen del 45%?"
+    why: "Spanish break-even ROAS math (1 ÷ margin) — a core deliverable, phrased in Spanish without the skill name."
+
+  - prompt: "La campanya de Meta no converteix des que vam activar el Consent Mode v2 — què s'ha trencat?"
+    why: "Catalan: conversions dropped after Consent Mode v2 — the measurement-setup gate (Advanced consent + Enhanced Conversions + CAPI) is owned here."
+
+should_not_trigger:
+  - prompt: "Write the landing page these ads point to."
+    route_to: landing-copy
+    why: "The destination page is the click target, not the ad-surface buy; landing-copy owns the page words."
+
+  - prompt: "Design an A/B test with proper sample size and statistical significance for our checkout."
+    route_to: ab-testing
+    why: "Experiment methodology — power, sample size, significance — is ab-testing's domain, not the media buy."
+
+  - prompt: "Should we even invest in paid this quarter, or focus on content and SEO?"
+    route_to: marketing
+    why: "The whether-to-run-paid / channel-mix decision sits one level up in marketing; ads only executes the paid buy inside that plan."
+
+  - prompt: "Build the dashboard that tracks our ad spend and revenue over time."
+    route_to: dashboard
+    why: "Constructing the reporting surface is dashboard's job; ads sets up the conversion signal but doesn't build the read-out."
+
+  - prompt: "Define the tone and voice our ad copy should speak in across every channel."
+    route_to: brand-voice
+    why: "The voice system the copy must obey is brand-voice; ads writes ad-surface copy that conforms to it."
+
+capability:
+  - scenario: "Given a product (gross margin 50%, target CPA $40) and the goal of scaling Meta acquisition, produce a launch plan."
+    must_include:
+      - "Picks a Meta surface (Advantage+ vs manual) with a one-line why tied to conversion-data volume / creative count."
+      - "Computes break-even ROAS = 1 ÷ 0.50 = 2.0x and sets a target ROAS at or above break-even (states scaling-mode 2x-3x or profit-mode higher explicitly)."
+      - "Derives the daily budget floor from ~50x target CPA (≈$2,000/day) or a staged ramp toward it."
+      - "States an existing-customer budget cap of 20-30% on Advantage+ and why (else delivery drifts to cheap retargeting)."
+      - "Asks for 15-20+ creative variations within platform char/count limits (no overflow)."
+      - "Includes a measurement-setup note: Consent Mode v2 (Advanced) + Enhanced Conversions + Meta CAPI."
+      - "Names incrementality / blended MER (not platform ROAS) as the scale-vs-kill decision, and the <=20%/week scaling rule."
+      - "Hands off destination to landing-copy, voice to brand-voice, experiment stats to ab-testing, reporting to analytics/dashboard."

package/skills/ads/references/platform-specs.md

@@ -0,0 +1,73 @@
+# Platform asset specs
+
+Hard limits per surface. The character counts are not advice — overflow gets the
+asset truncated or rejected, which drags the asset-group rating. Lint against these
+with `scripts/verify.sh` before shipping.
+
+*All counts/limits dated 2026-06-02. Sources: Google Ads Help answer/14528220 (PMax),
+answer/13704860 (Demand Gen); digitalapplied.com PMax 2026 guide; groas.com Demand Gen
+2026 guide; adligator.com / attnagency.com Advantage+ guides.*
+
+## Google Performance Max (per asset group)
+
+| Asset | Count | Limit |
+|---|---|---|
+| Headlines | up to 15 | 30 char each |
+| Long headline | 1 | 90 char |
+| Descriptions | up to 5 | 90 char each (one short ≤60 recommended) |
+| Images | up to 20 | landscape 1.91:1, square 1:1, portrait 4:5 |
+| Logos | up to 5 | 1:1 and 4:1 |
+| Videos | up to 5 | ≥10s; add your own — Google auto-generates poor ones if you don't |
+| Business name | 1 | 25 char |
+
+- **Asset groups:** max **25 per campaign**; start with **1–2** and only split when a
+  group has a distinct audience/theme and enough budget to feed it.
+- **Asset rating:** Google labels each asset **Low / Good / Best**. Replace **Low**
+  assets after **4–6 weeks** — a Low asset suppresses the whole group's reach.
+
+## Google Demand Gen
+
+| Asset | Count | Limit |
+|---|---|---|
+| Headlines | up to 5 | 40 char each |
+| Descriptions | up to 5 | 90 char each |
+| Images | per format | 1.91:1, 1:1, 4:5 |
+| Videos | per format | landscape / square / vertical |
+
+Demand Gen gives the control PMax withholds: **preview exact combinations**, **opt out
+of optimized targeting**, and **report by placement / audience / asset**. Reach for it
+when you need creative and audience control, not maximum automation.
+
+## Google Search — Responsive Search Ads
+
+| Asset | Count | Limit |
+|---|---|---|
+| Headlines | up to 15 | 30 char each |
+| Descriptions | up to 4 | 90 char each |
+
+Pin sparingly — pinning everything removes the algorithm's ability to test
+combinations.
+
+## Meta Advantage+ (Shopping / Sales)
+
+- Feed **15–20+ creative variations** across mixed orientations (1:1, 4:5, 9:16) so
+  the algorithm has material to compare; 3–5 creatives make it a manual campaign in
+  disguise.
+- Primary text, headline, and description fields exist per placement; Meta truncates
+  primary text in-feed around ~125 char — front-load the hook.
+- Set the **existing-customer budget cap at 20–30%**, or delivery drifts to cheap
+  retargeting reconversions and acquisition stalls.
+
+## Meta manual (ABO / CBO)
+
+Use for tight audience control, small budgets, or isolating a segment the algorithm
+would dilute. Same creative fields; you control the audience and budget split per
+ad set.
+
+## Google Ads API version note (for scripting)
+
+If you script against the API rather than the UI: Google moved to a **monthly release
+cadence in 2026**. Latest is **v24.1 (released 2026-05-13)**, preceded by v24
+(2026-04-22) and v23 (2026-01-28). Pin a version explicitly and watch the deprecation
+window. *Source: developers.google.com/google-ads/api/docs/release-notes — accessed
+2026-06-02.*

package/skills/ads/references/roas-model.md

@@ -0,0 +1,77 @@
+# ROAS model
+
+The money math that gates every campaign decision. Do this before structure.
+
+*Dated 2026-06-02. Sources: triplewhale.com break-even ROAS guide;
+bennettfinancials.com contribution-margin guide; kleene.ai ROAS guide.*
+
+## Break-even ROAS
+
+```text
+break-even ROAS = 1 ÷ gross-margin %
+```
+
+Gross margin here is **contribution margin** — price minus COGS, payment fees,
+shipping, and any per-order variable cost. Use the real number, not the headline
+markup.
+
+| Gross margin | Break-even ROAS |
+|---|---|
+| 30% | 3.33x |
+| 40% | 2.50x |
+| 50% | 2.00x |
+| 60% | 1.67x |
+| 70% | 1.43x |
+
+A campaign whose target ROAS sits **below** the break-even row is losing money on
+every conversion. There is no targeting fix for that — change the offer, the margin,
+or the target.
+
+## Target ROAS by stage
+
+| Mode | Meta target | Google Search target | Judge on |
+|---|---|---|---|
+| Profit | 3.5x–5x | 5x–8x | Campaign ROAS, validated incremental |
+| Scaling | 2x–3x | 2x–3x | Blended MER (you trade margin for growth on purpose) |
+
+Always set **target ≥ break-even**. Scaling-mode targets near break-even are a
+deliberate growth bet, not an accident — name it as such.
+
+## Why the platform number lies
+
+| Number | What it measures | Trust for |
+|---|---|---|
+| **Platform ROAS** | Last-click, per-platform; double-counts across surfaces | Nothing on its own — over-reports 30–100% |
+| **Blended MER** | Total revenue ÷ total ad spend, all channels | The scaling decision |
+| **Incremental ROAS** | Revenue that would NOT have happened without the ad | The truth — usually 30–60% of the platform number |
+
+Platform-reported ROAS credits the ad for sales that would have closed anyway
+(brand searches, returning customers, organic-assisted). Incrementality strips that
+out.
+
+## Geo-holdout test design
+
+The 2026 gold standard for validating real lift:
+
+1. Split comparable regions into **test** (ads on) and **control** (ads off / held
+   out). Match on baseline revenue and seasonality.
+2. Run for a clean window (≥2–4 weeks, longer than the purchase cycle).
+3. Incremental revenue = test-region revenue − control-region revenue (scaled to
+   equal population/baseline).
+4. **Incremental ROAS = incremental revenue ÷ test-region ad spend.**
+5. Compare that incremental ROAS to break-even — not the platform number.
+
+Ghost-ad / PSA-holdout tests are the on-platform equivalent when geo-splits aren't
+feasible. For the statistical design (power, significance, sample size) hand off to
+the `ab-testing` skill — this is the media-side framing, not the experiment math.
+
+## Scale / hold / kill rule
+
+| Incremental ROAS vs break-even | Decision |
+|---|---|
+| Comfortably above break-even AND stable ≥2 weeks | **Scale** — ≤20%/week, don't reset learning |
+| Near break-even or noisy | **Hold** — keep structure ≥4 weeks, gather data, fix creative/signal first |
+| Below break-even after the learning phase | **Kill** — or fix margin/offer; no bid tweak rescues negative unit economics |
+
+Never scale on the platform dashboard. Scale on incremental ROAS or blended MER, and
+only after the learning phase has stabilized.