Open-source SEO, GEO, and marketing skills for AI agents.
feat(google-ads): record lead quality and linked accounts; drop baseline file (#129)
Tong Chen34f5f67f9b05
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 478f12cf..46b8ec34 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "The official ads, analytics, SEO, and GEO plugin from NotFair.",- "version": "0.27.12"+ "version": "0.27.13"},"plugins": [{"name": "notfair","source": "./","description": "Operate Google, Meta, X, LinkedIn, Reddit, and TikTok Ads; WordPress and GoHighLevel; analyze Search Console and GA4; and run open-source SEO, GEO, and content workflows.",- "version": "0.27.12",+ "version": "0.27.13","author": {"name": "NotFair","url": "https://notfair.co"diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex dc1701ff..5dcf75e7 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.12",+ "version": "0.27.13","description": "The official ads, analytics, SEO, and GEO plugin from NotFair. Operate Google, Meta, X, LinkedIn, Reddit, and TikTok Ads; WordPress and GoHighLevel; analyze Google Search Console and GA4; and run open-source search and content workflows from any compatible agent.","author": {"name": "NotFair",diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex 2c60b6e0..cc90f98f 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.12",+ "version": "0.27.13","description": "The official ads, analytics, SEO, and GEO plugin from NotFair.","author": {"name": "NotFair",diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.jsonindex 2f536cb3..8150ce86 100644--- a/.cursor-plugin/plugin.json+++ b/.cursor-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "notfair","displayName": "NotFair",- "version": "0.27.12",+ "version": "0.27.13","description": "One NotFair OAuth MCP for Google, Meta, X, LinkedIn, Reddit, and TikTok Ads, GA4, Search Console, GoHighLevel, and WordPress, plus open-source SEO, GEO, and content skills.","author": {"name": "Notfair",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e28f72b9..21abb7fd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,6 +9,15 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).## [Unreleased]+## [0.27.13] — 2026-09-25++### Changed++- Google Ads business context records lead quality and linked accounts. `lead_quality` notes what the primary conversion actually counts, where leads become customers, how a lead joins back to a click, and the qualified or booked rate by campaign. `linked_accounts` lists other ad accounts for the same business, such as Local Services Ads. The audit asks for them on lead-gen accounts, and the local lead-gen playbook compares campaigns on cost per booking when the rates exist.+- Anomaly checks compare the last 7 complete days with the prior 28 in the performance read the skill already makes, instead of maintaining a local `account-baseline.json`.+- Audits build personas only when the task needs them or copy/landing work is next, instead of on every full audit.+- Experiment readouts judge a partial-campaign change on the part that changed, not arm totals. Bid-strategy guidance checks uploaded values against the most recent matured cohort before moving to value-based bidding.+## [0.27.12] — 2026-09-23### Fixeddiff --git a/VERSION b/VERSIONindex 26363026..bfac895f 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.27.12+0.27.13diff --git a/gemini-extension.json b/gemini-extension.jsonindex f2c3ada7..ac6eee1a 100644--- a/gemini-extension.json+++ b/gemini-extension.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.12",+ "version": "0.27.13","description": "Operate ads and analytics, and run open-source SEO, GEO, and content workflows with NotFair.","contextFileName": "AGENTS.md","mcpServers": {diff --git a/google-ads/audit/SKILL.md b/google-ads/audit/SKILL.mdindex a33c1554..70b77be5 100644--- a/google-ads/audit/SKILL.md+++ b/google-ads/audit/SKILL.md@@ -17,11 +17,11 @@ Follow `../shared/preamble.md` (MCP detection, account selection) and `../shared| Artifact | Path | When ||---|---|---|| Business context | `{data_dir}/business-context.json` | First full audit, or refresh when `audit_date` is >90 days old. Skip on scoped audits if file is fresh. |-| Personas | `{data_dir}/personas/{accountId}.json` | Every full audit. |+| Personas | `{data_dir}/personas/{accountId}.json` | Only when the task needs them (ad copy, landing pages, audience work) or copy/landing work is next and none exist. |-These are the handoff to every other ads skill — write them even if the report is short. Otherwise `/google-ads-copy` and `/google-ads-landing` operate without business context and produce generic output.+Business context is the handoff to every other ads skill — write it even if the report is short. Otherwise `/google-ads-copy` and `/google-ads-landing` operate without business context and produce generic output.-**business-context.json schema:** `business_name, industry, website, services[], locations[], target_audience, brand_voice{tone, words_to_use[], words_to_avoid[]}, differentiators[], competitors[], seasonality{peak_months[], slow_months[], seasonal_hooks[]}, keyword_landscape{high_intent_terms[], competitive_terms[], long_tail_opportunities[]}, social_proof[], offers_or_promotions[], landing_pages{}, unit_economics{aov_usd, profit_margin, source}, notes, audit_date, account_id`.+**business-context.json schema:** `business_name, industry, website, services[], locations[], target_audience, brand_voice{tone, words_to_use[], words_to_avoid[]}, differentiators[], competitors[], seasonality{peak_months[], slow_months[], seasonal_hooks[]}, keyword_landscape{high_intent_terms[], competitive_terms[], long_tail_opportunities[]}, social_proof[], offers_or_promotions[], landing_pages{}, unit_economics{aov_usd, profit_margin, source}, lead_quality{primary_conversion_definition, crm_source, join_key, qualified_rate_by_campaign{}, last_confirmed}, linked_accounts[{account_id, type, note}], notes, audit_date, account_id`. See `references/business-context.md` for `lead_quality` and `linked_accounts`.**personas JSON schema:** `{account_id, saved_at, personas: [{name, demographics, primary_goal, pain_points[], search_terms[], decision_trigger, value}]}`. See `references/persona-discovery.md`.@@ -105,11 +105,11 @@ Derive what you can from data already pulled:Then crawl the website (homepage + about + services + top 3 ad landing pages, parallel `WebFetch`) and merge into the schema. See `references/business-context.md`.-Ask the user — it's faster than guessing — for: differentiators, competitors, seasonality, unit economics (AOV, margin). Ask for everything else only if the data + crawl can't answer it.+Ask the user — it's faster than guessing — for: differentiators, competitors, seasonality, unit economics (AOV, margin). For lead-gen accounts, also ask how a lead becomes a customer (the CRM or booking system, and the qualified or booked rate by campaign if known) and whether other ad accounts serve the same business (for example Local Services Ads), since this account's data can't show either. Ask for everything else only if the data + crawl can't answer it.## Phase 5 — Personas-Discover 2–3 personas from search terms, top keywords, ad-group themes, landing pages, geo, and device split — all from the dataset already in memory. Persist to `{data_dir}/personas/{accountId}.json`. Each persona must be grounded in **5+ actual search terms**; if not, drop it. See `references/persona-discovery.md`.+Skip this phase unless the user's task needs personas or copy/landing work is next and no personas file exists. Otherwise, discover 2–3 personas from search terms, top keywords, ad-group themes, landing pages, geo, and device split — all from the dataset already in memory. Persist to `{data_dir}/personas/{accountId}.json`. Each persona must be grounded in **5+ actual search terms**; if not, drop it. See `references/persona-discovery.md`.## Phase 6 — Report@@ -123,6 +123,6 @@ State where any audit artifacts were actually saved. Do not claim hosted audit h1. **Read-only skill.** Diagnose; don't mutate. Every fix routes through `/google-ads` (or `/google-ads-copy`, `/google-ads-landing`). End the report with one handoff tied to the #1 action.2. **STOP condition.** If conversion tracking is broken, recommend pausing spend until it's fixed before recommending anything else.-3. **Always persist** `business-context.json` and `personas/{accountId}.json` even if the report is short — downstream skills depend on them.+3. **Always persist** `business-context.json` even if the report is short — downstream skills depend on it. Save `personas/{accountId}.json` whenever Phase 5 ran.4. **Name names.** Every finding cites specific campaigns, keywords, search terms, and dollar amounts. No generic verdicts.5. **Show the data, not the score.** The pulse metrics are the verdict — three numbers with named contributors and pointers to the fix. No letter grades, no 0–5 ratings hiding the reasoning behind a label.diff --git a/google-ads/audit/references/business-context.md b/google-ads/audit/references/business-context.mdindex bdaca777..34d0c93d 100644--- a/google-ads/audit/references/business-context.md+++ b/google-ads/audit/references/business-context.md@@ -88,6 +88,14 @@ Write the complete business context to `{data_dir}/business-context.json`:"source": "user_provided | inferred_from_template | unknown","last_confirmed": ""},+ "lead_quality": {+ "primary_conversion_definition": "",+ "crm_source": "",+ "join_key": "",+ "qualified_rate_by_campaign": {},+ "last_confirmed": ""+ },+ "linked_accounts": [],"social_proof": [],"offers_or_promotions": [],"landing_pages": {},@@ -111,6 +119,18 @@ Unit economics drive margin-aware profitability framing (see `../../shared/ppc-m**Never compute break-even CPA when `source == "inferred_from_template"` without surfacing the assumption.** A template-inferred margin that's off by 15% changes every dollar-impact figure in the audit. Transparency is non-negotiable.+## Lead Quality and Linked Accounts — How to Populate++For lead-gen accounts, the primary Google Ads conversion often overstates leads: a form conversion can fire on repeat submits and existing customers. Record what the business can tell you, and leave fields empty rather than guessing.++- `primary_conversion_definition`: what the primary conversion actually counts (for example "every phone-form submit, including repeats").+- `crm_source`: where leads are deduplicated and turn into customers (a CRM, a booking system).+- `join_key`: how a lead links back to an ad click, if the business stores one (for example a gclid captured in a UTM field).+- `qualified_rate_by_campaign`: the share of each campaign's leads that became qualified, booked or paying, with the window it was measured over.+- `linked_accounts`: other ad accounts that serve the same business, such as Local Services Ads, with their account IDs. An audit of one account cannot see their spend or leads.++When `qualified_rate_by_campaign` exists, compare campaigns on cost per qualified lead or booking, not Google-reported CPL alone.+### Industry template matchingDuring Phase 3, after resolving `industry`, also set `industry_template_key` by matching against `templates.*.aliases` in `industry-templates.json` (case-insensitive substring). If no match, use `"generic"`. This key is the stable handle downstream skills use — industry names drift across audits, the key doesn't.diff --git a/google-ads/manage/SKILL.md b/google-ads/manage/SKILL.mdindex fcb048ab..cdbdc9d4 100644--- a/google-ads/manage/SKILL.md+++ b/google-ads/manage/SKILL.md@@ -85,28 +85,9 @@ These live alongside this skill. Read on demand — not preemptively.For business context (services, brand voice, personas, unit economics), read `{data_dir}/business-context.json` and `{data_dir}/personas/{accountId}.json`. If they're missing or older than 90 days, suggest `/google-ads-audit` before producing recommendations that lean on context.-## Account baseline--Maintain `{data_dir}/account-baseline.json` for cross-session anomaly detection. Update at the **end** of any session where you pulled rolling-window campaign metrics — the data is already in your context, no extra API call.--```json-{- "accountId": "<from config>",- "lastUpdated": "<ISO 8601>",- "campaigns": {- "<campaignId>": {- "name": "<campaign name>",- "rolling30d": { "avgDailySpend": 0, "totalConversions": 0, "avgCpa": 0, "avgCtr": 0, "avgConvRate": 0, "totalSpend": 0 },- "recent7d": { "spend": 0, "conversions": 0, "cpa": 0, "ctr": 0, "clicks": 0, "impressions": 0 },- "snapshotDate": "<ISO 8601>"- }- }-}-```--Update formula: `rolling30d = (0.7 × previous_rolling30d) + (0.3 × recent7d × (30/7))`. New campaigns: initialize `rolling30d` from `recent7d` directly. Cap at 50 campaigns (spend > $0 in last 30 days) so the file stays small.--When the baseline is older than 24h, see `references/session-checks.md` for the anomaly comparison.+## Anomaly check++For cross-session anomaly detection, compare each campaign's last 7 complete days with its prior 28 complete days in the same read you already make for performance. Do not maintain a local baseline file; live data is the baseline. See `references/session-checks.md`.## Conditional handoffsdiff --git a/google-ads/manage/references/bid-strategy-decision-tree.md b/google-ads/manage/references/bid-strategy-decision-tree.mdindex eb2c5c37..281dc2cb 100644--- a/google-ads/manage/references/bid-strategy-decision-tree.md+++ b/google-ads/manage/references/bid-strategy-decision-tree.md@@ -37,6 +37,7 @@ These are candidates, not automatic answers. Availability and labels vary by cam- For uncertainty, use **Save as experiment** or the supported experiment capability when available.- After target or conversion-goal changes, assess mature results over the relevant conversion cycle. Google's current guidance says one to two conversion cycles are commonly needed; the account's displayed status and lag take precedence over a fixed number of days.- Intervene earlier only when a policy, tracking, capacity, or spend guardrail is breached. State that override explicitly.+- Before moving to value-based bidding, check the uploaded values against the most recent cohort that has matured. Values averaged over a long history can overstate or understate the customers the account acquires today, and Smart Bidding will act on that gap.## Troubleshooting before changing targetsdiff --git a/google-ads/manage/references/decision-quality.md b/google-ads/manage/references/decision-quality.mdindex abbe15b3..0bf191a5 100644--- a/google-ads/manage/references/decision-quality.md+++ b/google-ads/manage/references/decision-quality.md@@ -60,7 +60,7 @@ Before sending the answer, recalculate the decisive values and verify that the r- **Observe** when exposure is small, data is immature, or a later conversion could reverse the conclusion.- **Stage a reversible change** when downside is bounded and operational urgency matters. Change one decision lever, record before/after state, and wait for the defined maturity window.-- **Run an experiment** when the change is material and causality matters. State a business-linked hypothesis, test one variable, preselect one or two success metrics, preserve the base campaign while the test is running, and use the platform result plus mature conversions before choosing a winner.+- **Run an experiment** when the change is material and causality matters. State a business-linked hypothesis, test one variable, preselect one or two success metrics, preserve the base campaign while the test is running, and use the platform result plus mature conversions before choosing a winner. When the treatment changes only part of a campaign (one ad group's landing page or ads), read the result on the part that changed; arm totals can be driven by ad groups the treatment did not touch.- **Act protectively** before full maturity only for policy, safety, broken measurement with uncontrolled exposure, obvious irrelevant intent, or a breached spend/business guardrail. Explain why the normal evidence bar is being overridden.### Common ambiguity gatesdiff --git a/google-ads/manage/references/session-checks.md b/google-ads/manage/references/session-checks.mdindex 405a45e1..7545d4f7 100644--- a/google-ads/manage/references/session-checks.md+++ b/google-ads/manage/references/session-checks.md@@ -43,13 +43,10 @@ Do not declare the primary outcome early. You may still pull safety, spend, deli5. If the predeclared rollback threshold is breached on mature, comparable evidence, recommend the recorded rollback. If no threshold was recorded, classify the result as observed/inconclusive and ask for the business guardrail rather than inventing one after seeing the outcome.-## Check account baseline for anomalies+## Check for anomalies-Read `{data_dir}/account-baseline.json`. If it exists AND was last updated >24 hours ago:+In the same performance read you already make, compare each campaign's last 7 complete days with its prior 28 complete days (scaled to a 7-day rate):-1. Compare each campaign's most recent complete window with a like-for-like mature baseline.-2. Flag movements that cross a stored account-specific anomaly band or business guardrail. If none exists, rank the largest standardized or percentage movements for review and label them as triage signals, not failures.+1. Use complete days in the account's time zone. Mark campaigns whose budget, bidding or status changed inside either window, so a movement caused by that change is reported with it, not as an unexplained anomaly.+2. Flag movements that cross an account-specific anomaly band or business guardrail. If none exists, rank the largest movements for review and label them as triage signals, not failures.3. Mention anomalies briefly if found.-4. Update the baseline (see Account Baseline section in SKILL.md).--If `account-baseline.json` doesn't exist, skip — it will be created at session end.diff --git a/google-ads/shared/local-leadgen-playbook.md b/google-ads/shared/local-leadgen-playbook.mdindex 72dfa7cf..51489bad 100644--- a/google-ads/shared/local-leadgen-playbook.md+++ b/google-ads/shared/local-leadgen-playbook.md@@ -37,6 +37,10 @@ Google Ads conversions are not enough. When possible, connect:Judge terms by qualified lead or booking quality once that data exists.+- Check what the primary conversion counts before comparing CPLs. A form conversion that fires on every submit can report well above the leads the CRM keeps, and the gap can differ by campaign.+- Keep the qualified or booked rate per campaign in `business-context.json` (`lead_quality`) and compare campaigns on cost per booking. Two campaigns with the same CPL can differ several times over in cost per booked customer.+- Ask whether the business runs other ad accounts for the same locations, especially Local Services Ads. Record them under `linked_accounts`; budget moves between Search and LSA need both views.+## Output prioritiesFor local accounts, reports should emphasize:diff --git a/plugin.json b/plugin.jsonindex 4816f4a9..f994c364 100644--- a/plugin.json+++ b/plugin.json@@ -1,7 +1,7 @@{"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "notfair",- "version": "0.27.12",+ "version": "0.27.13","description": "Operate Google, Meta, X, LinkedIn, Reddit, and TikTok Ads plus GA4, Search Console, GoHighLevel, and WordPress through one OAuth MCP, and run open-source SEO, GEO, and content workflows.","author": {"name": "NotFair",diff --git a/server.json b/server.jsonindex 3ba34d9a..4ce2dca6 100644--- a/server.json+++ b/server.json@@ -8,7 +8,7 @@"url": "https://github.com/nowork-studio/notfair-plugin","source": "github"},- "version": "0.27.12",+ "version": "0.27.13","remotes": [{"type": "streamable-http",