Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

fix: support cached business context schema

Tong4e999af47554
diff --git a/google-ads/copy/SKILL.md b/google-ads/copy/SKILL.md
index 3a3b25ef..98f2e367 100644
--- a/google-ads/copy/SKILL.md
+++ b/google-ads/copy/SKILL.md
@@ -111,7 +111,7 @@ Read `{data_dir}/business-context.json` `competitors` and `differentiators` fiel
| DO use specific features competitors lack | "Same-Day Service" beats "Better Service". Specificity implies superiority without claiming it |
| DO use pricing advantage if real | "Flat-Rate Pricing" or "From $99" differentiates against competitors with opaque pricing |
| DO use trust signals aggressively | "25+ Years", "4.9★ Google Rating", "500+ 5-Star Reviews" — these are verifiable and powerful |
-| DO use location specificity | "Seattle's Own [Service]" or "Locally Owned Since 1998" differentiates against national chains |
+| DO use location specificity | "Example City's Own [Service]" or "Locally Owned Since 1998" differentiates against national chains |
| DO use speed/convenience | "Same-Day", "24/7", "Book Online in 60 Seconds" — operational advantages competitors may not match |
| DO use guarantees | "Satisfaction Guaranteed", "Free Re-Service", "No Fix, No Fee" — risk reversal converts |
diff --git a/google-ads/copy/evals/evals.json b/google-ads/copy/evals/evals.json
index 42047c26..8bbc40ff 100644
--- a/google-ads/copy/evals/evals.json
+++ b/google-ads/copy/evals/evals.json
@@ -12,7 +12,7 @@
"All headlines are <= 30 characters",
"Every description shows a character count",
"All descriptions are <= 90 characters",
- "At least one headline includes Seattle (location specificity)",
+ "At least one headline includes Example City (location specificity)",
"At least one headline references the 4.8 star rating or 200+ reviews (social proof)",
"At least one headline references 12 years in business (trust signal)",
"Pin positions are indicated (at least H1 pinned to position 1)"
diff --git a/google-ads/manage/evals/evals.json b/google-ads/manage/evals/evals.json
index 92e915ab..26ebe23f 100644
--- a/google-ads/manage/evals/evals.json
+++ b/google-ads/manage/evals/evals.json
@@ -15,14 +15,14 @@
},
{
"id": 2,
- "prompt": "Here's my Google Ads data. I have 3 campaigns:\n\n```json\n{\"campaigns\": [{\"name\": \"Brand - Acme Plumbing\", \"id\": \"111\", \"status\": \"ENABLED\", \"spend_30d\": 2400, \"clicks\": 890, \"impressions\": 12000, \"conversions\": 45, \"cpa\": 53.33, \"ctr\": 7.4}, {\"name\": \"Non-Brand - Emergency Plumbing\", \"id\": \"222\", \"status\": \"ENABLED\", \"spend_30d\": 4800, \"clicks\": 620, \"impressions\": 18000, \"conversions\": 12, \"cpa\": 400.00, \"ctr\": 3.4}, {\"name\": \"Non-Brand - Drain Cleaning\", \"id\": \"333\", \"status\": \"ENABLED\", \"spend_30d\": 1800, \"clicks\": 410, \"impressions\": 9500, \"conversions\": 18, \"cpa\": 100.00, \"ctr\": 4.3}],\n\"keywords\": [{\"campaign\": \"Non-Brand - Emergency Plumbing\", \"keyword\": \"emergency plumber near me\", \"spend\": 1200, \"clicks\": 180, \"conversions\": 8, \"cpa\": 150, \"qs\": 7}, {\"keyword\": \"24 hour plumbing service\", \"campaign\": \"Non-Brand - Emergency Plumbing\", \"spend\": 1800, \"clicks\": 220, \"conversions\": 0, \"cpa\": null, \"qs\": 3}, {\"keyword\": \"plumber salary\", \"campaign\": \"Non-Brand - Emergency Plumbing\", \"spend\": 450, \"clicks\": 95, \"conversions\": 0, \"cpa\": null, \"qs\": 2}, {\"keyword\": \"drain cleaning service\", \"campaign\": \"Non-Brand - Drain Cleaning\", \"spend\": 900, \"clicks\": 210, \"conversions\": 14, \"cpa\": 64.29, \"qs\": 8}],\n\"search_terms\": [{\"term\": \"how to become a plumber\", \"clicks\": 42, \"conversions\": 0, \"spend\": 180}, {\"term\": \"plumbing apprenticeship\", \"clicks\": 28, \"conversions\": 0, \"spend\": 120}, {\"term\": \"emergency plumber seattle\", \"clicks\": 35, \"conversions\": 6, \"spend\": 210}]}\n```\n\nHow are my ads doing? What should I fix?",
- "expected_output": "A performance analysis that identifies specific waste: the 'plumber salary' keyword ($450 spent, 0 conversions, QS 2) should be paused immediately; '24 hour plumbing service' ($1800, 0 conversions, QS 3) needs urgent attention; 'how to become a plumber' and 'plumbing apprenticeship' should be added as negative keywords. The Emergency Plumbing campaign has a $400 CPA which is far above the Drain Cleaning campaign's $100 CPA. Should recommend adding 'emergency plumber seattle' as a keyword since it has 6 conversions.",
+ "prompt": "Here's my Google Ads data. I have 3 campaigns:\n\n```json\n{\"campaigns\": [{\"name\": \"Brand - Acme Plumbing\", \"id\": \"111\", \"status\": \"ENABLED\", \"spend_30d\": 2400, \"clicks\": 890, \"impressions\": 12000, \"conversions\": 45, \"cpa\": 53.33, \"ctr\": 7.4}, {\"name\": \"Non-Brand - Emergency Plumbing\", \"id\": \"222\", \"status\": \"ENABLED\", \"spend_30d\": 4800, \"clicks\": 620, \"impressions\": 18000, \"conversions\": 12, \"cpa\": 400.00, \"ctr\": 3.4}, {\"name\": \"Non-Brand - Drain Cleaning\", \"id\": \"333\", \"status\": \"ENABLED\", \"spend_30d\": 1800, \"clicks\": 410, \"impressions\": 9500, \"conversions\": 18, \"cpa\": 100.00, \"ctr\": 4.3}],\n\"keywords\": [{\"campaign\": \"Non-Brand - Emergency Plumbing\", \"keyword\": \"emergency plumber near me\", \"spend\": 1200, \"clicks\": 180, \"conversions\": 8, \"cpa\": 150, \"qs\": 7}, {\"keyword\": \"24 hour plumbing service\", \"campaign\": \"Non-Brand - Emergency Plumbing\", \"spend\": 1800, \"clicks\": 220, \"conversions\": 0, \"cpa\": null, \"qs\": 3}, {\"keyword\": \"plumber salary\", \"campaign\": \"Non-Brand - Emergency Plumbing\", \"spend\": 450, \"clicks\": 95, \"conversions\": 0, \"cpa\": null, \"qs\": 2}, {\"keyword\": \"drain cleaning service\", \"campaign\": \"Non-Brand - Drain Cleaning\", \"spend\": 900, \"clicks\": 210, \"conversions\": 14, \"cpa\": 64.29, \"qs\": 8}],\n\"search_terms\": [{\"term\": \"how to become a plumber\", \"clicks\": 42, \"conversions\": 0, \"spend\": 180}, {\"term\": \"plumbing apprenticeship\", \"clicks\": 28, \"conversions\": 0, \"spend\": 120}, {\"term\": \"emergency plumber example-city\", \"clicks\": 35, \"conversions\": 6, \"spend\": 210}]}\n```\n\nHow are my ads doing? What should I fix?",
+ "expected_output": "A performance analysis that identifies specific waste: the 'plumber salary' keyword ($450 spent, 0 conversions, QS 2) should be paused immediately; '24 hour plumbing service' ($1800, 0 conversions, QS 3) needs urgent attention; 'how to become a plumber' and 'plumbing apprenticeship' should be added as negative keywords. The Emergency Plumbing campaign has a $400 CPA which is far above the Drain Cleaning campaign's $100 CPA. Should recommend adding 'emergency plumber example-city' as a keyword since it has 6 conversions.",
"files": [],
"expectations": [
"Identifies 'plumber salary' keyword as waste — names it specifically with the $450 spend and 0 conversions",
"Identifies '24 hour plumbing service' as problematic — $1800 spend, 0 conversions, QS 3",
"Recommends adding 'how to become a plumber' and 'plumbing apprenticeship' as negative keywords",
- "Recommends adding 'emergency plumber seattle' as a keyword since it has 6 conversions",
+ "Recommends adding 'emergency plumber example-city' as a keyword since it has 6 conversions",
"Flags the Emergency Plumbing campaign's $400 CPA as significantly worse than Drain Cleaning's $100 CPA",
"Calculates or estimates wasted spend with a dollar amount",
"Recommendations include specific keyword names and campaign names, not generic advice"
diff --git a/google-ads/shared/ppc-math.md b/google-ads/shared/ppc-math.md
index 9169d6ec..56b0efc2 100644
--- a/google-ads/shared/ppc-math.md
+++ b/google-ads/shared/ppc-math.md
@@ -115,10 +115,10 @@ MER captures organic, brand, and retention — so it's higher than paid ROAS and
## Usage in Findings
**Before (account-average framing):**
-> "Keyword 'emergency plumber seattle' has CPA of $72, which is 150% of account average."
+> "Keyword 'emergency plumber example-city' has CPA of $72, which is 150% of account average."
**After (margin-aware framing, requires `margin=0.4`, `aov=$180` from business-context.json):**
-> "Keyword 'emergency plumber seattle' has CPA of $72. Your Break-Even CPA is $72 (AOV $180 × 40% margin) — every conversion from this keyword nets $0 profit. Either improve CVR or pause."
+> "Keyword 'emergency plumber example-city' has CPA of $72. Your Break-Even CPA is $72 (AOV $180 × 40% margin) — every conversion from this keyword nets $0 profit. Either improve CVR or pause."
**Headroom example:**
> "Example City Search is profitable: CPA $18, Break-Even $72, **~$2,700/mo headroom** at 50 conversions. Budget-Lost IS is 35% — raising budget by $1,500/mo could capture ~$5,000 more revenue."
diff --git a/openclaw/bin/weekly_review.py b/openclaw/bin/weekly_review.py
index f522ff5d..baf42335 100755
--- a/openclaw/bin/weekly_review.py
+++ b/openclaw/bin/weekly_review.py
@@ -935,7 +935,16 @@ def business_context_local_label(business_context: dict[str, Any] | None) -> str
geography = str(context.get("primary_geography") or "").strip()
if geography:
return geography
- locations = context.get("location_priorities") or context.get("locations") or []
+ location_priorities = context.get("location_priorities")
+ if isinstance(location_priorities, dict):
+ priority_order = {"high": 0, "medium": 1, "low": 2}
+ ranked_locations = sorted(
+ location_priorities.items(),
+ key=lambda item: priority_order.get(str((item[1] or {}).get("priority", "") if isinstance(item[1], dict) else "").lower(), 3),
+ )
+ if ranked_locations:
+ return "/".join(str(location) for location, _details in ranked_locations[:3])
+ locations = context.get("target_locations") or context.get("locations") or location_priorities or []
values = context_values(locations)
if values:
return "/".join(str(value) for value in values[:3])
@@ -981,13 +990,26 @@ def business_context_says_national_deprioritized(business_context: dict[str, Any
return "national" in text or "outside service area" in text or "non-local" in text
+def booking_intent_terms(hierarchy: Any) -> tuple[list[Any], list[Any]]:
+ if isinstance(hierarchy, dict):
+ return context_values(hierarchy.get("highest_priority", [])), context_values(hierarchy.get("supporting_only", []))
+ ordered = context_values(hierarchy)
+ if not ordered:
+ return [], []
+ high_priority = ordered[:1]
+ supporting = ordered[1:]
+ informational_markers = ("cost", "price", "how much", "average", "guide", "research", "compare")
+ for term in ordered:
+ if any(marker in str(term).lower() for marker in informational_markers) and term not in supporting:
+ supporting.append(term)
+ return high_priority, supporting
+
def apply_business_context_to_issue(issue: dict[str, Any], business_context: dict[str, Any] | None, site_id: str | None = None) -> dict[str, Any]:
if not business_context:
return issue
query = issue.get("primary_query")
hierarchy = business_context.get("booking_intent_hierarchy") or {}
- supporting_terms = hierarchy.get("supporting_only", []) if isinstance(hierarchy, dict) else []
- high_priority_terms = hierarchy.get("highest_priority", []) if isinstance(hierarchy, dict) else []
+ high_priority_terms, supporting_terms = booking_intent_terms(hierarchy)
page_roles = business_context.get("page_role_map") or {}
target = issue.get("target") or issue.get("canonical_target") or issue.get("raw_target")
reference_url = target or (business_context or {}).get("target_url") or (f"https://www.{site_id}" if site_id else None)
diff --git a/openclaw/shared/recommendation-quality.md b/openclaw/shared/recommendation-quality.md
index f1504329..99f4217f 100644
--- a/openclaw/shared/recommendation-quality.md
+++ b/openclaw/shared/recommendation-quality.md
@@ -15,7 +15,7 @@ Each recommendation should expose the inputs that drove ranking:
- `goal_alignment_score` — whether the signal supports the active goal, especially non-brand growth
- `actionability_score` — whether there is a clear SEO lever vs a vague investigation
- `business_intent_score` — whether the query likely maps to revenue, not just informational visits
-- `business_context_goal_score` — whether the opportunity matches the site-specific business goal, e.g. Seattle/local bookings over national informational traffic
+- `business_context_goal_score` — whether the opportunity matches the site-specific business goal, e.g. local qualified outcomes over national informational traffic
- `url_quality_score` — whether the URL is canonical/actionable or a tracking/parameter variant
- `learned_multiplier` — site-local prior from previous outcomes
@@ -39,7 +39,7 @@ These are not hard approval rules. They are decision levers for the operator and
- For informational price queries, classify the action as snippet/content packaging or query-intent mapping unless a SERP diagnosis proves metadata is the main lever.
- Explain why the top action is actionable and what would make it unsafe or low-confidence.
- Before proposing an edit for CTR/snippet/content opportunities, automatically run a deep-dive diagnostic: SERP snapshot, current title/meta/H1, above-the-fold content packaging, CTA/price-answer check, and zero-click risk classification.
-- If business context deprioritizes a traffic class, reframe the recommendation instead of chasing raw clicks. Example: for a local service business that only values Seattle bookings, broad national cost-query CTR should become a local intent ownership / consolidation proposal, not a national blog CTR optimization.
+- If business context deprioritizes a traffic class, reframe the recommendation instead of chasing raw clicks. Example: for a local service business that only values local qualified outcomes, broad national cost-query CTR should become a local intent ownership / consolidation proposal, not a national blog CTR optimization.
- If business-impact context is incomplete, create an explicit `business_context_request` queue item and surface the questions in the runner result instead of burying them in verification warnings. Missing business context blocks approval/editing, but should not block the diagnostic deep dive.
## Approval boundary