Open-source SEO, GEO, and marketing skills for AI agents.
v0.23.0 chore: fully strip legacy AdsAgent branding from active code
Yuting Zhongdea1520d959d
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 5150387b..d1c4191a 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO, GEO, Google Ads, and Meta Ads skills for Claude Code.",- "version": "0.22.0"+ "version": "0.23.0"},"plugins": [{"name": "toprank","source": "./","description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, GSC-driven content planning + local calendar viewer, opt-in OpenClaw cron publisher to a NotFair webhook, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",- "version": "0.22.0",+ "version": "0.23.0","author": {"name": "NotFair","url": "https://notfair.co"diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex abc83d14..b595cf49 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "toprank",- "version": "0.22.0",+ "version": "0.23.0","description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.","author": {"name": "NotFair",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1cde1fe5..eddd7092 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,65 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).---+## [0.23.0] — 2026-05-16++### Changed — full removal of legacy AdsAgent branding from active code++- The legacy AdsAgent brand is now fully removed from all **active** skill+ text, docs, MCP detection logic, install tests, and project guidance.+ CHANGELOG history is intentionally preserved verbatim — past releases+ shipped under that name and the historical record reflects that.+- **`google-ads/shared/preamble.md`** — dropped the one-time+ `.adsagent` → `.notfair` filesystem migration step entirely. Renumbered+ the remaining steps (Resolve config → Step 1, MCP detection → Step 2,+ Onboarding → Step 3, Calling tools → Step 4). MCP prefix detection now+ only looks for NotFair / NotFair-GoogleAds variants; the legacy+ `mcp__adsagent__*` / `mcp__claude_ai_AdsAgent__*` prefixes have been+ removed from the detection table, the legacy-prefix nudge, and the+ tool-call prefix reference list.+- **`gemini/SKILL.md`** — Step 2a (Google Ads change detection) no longer+ scans for the legacy MCP prefix or the legacy `.adsagent/` data-dir+ path.+- **`google-ads/shared/preamble.md`**, **`google-ads/shared/analysis-principles.md`**,+ **`google-ads/audit/SKILL.md`**, **`google-ads/manage/SKILL.md`** — the four+ active references to MCP playbook resources use `notfair://playbooks/*`+ rather than the prior `adsagent://` scheme.+- **`CLAUDE.md`** — "Branding: NotFair going forward" rewritten to+ "Branding: NotFair." The load-bearing-compat carve-out is gone (there+ is nothing left to carve out). The "Related repos" mention of the+ sibling `adsagent-plugin/` directory has been removed.+- **`README.md`** — Connectors table no longer mentions+ `mcp__adsagent__*` as a detected variant.+- **`test/install.test.sh`** — dropped the assertion that skills don't+ inline the legacy MCP prefix. The current assertion (no inline+ `mcp__notfair__listConnectedAccounts`) still guards against bypassing+ the shared preamble's prefix-detection logic.++### Coordination requirement (read before shipping)++- The `NotFair-GoogleAds` MCP server must publish the three playbook+ resources (`audit-account`, `explain-regression`, `run-experiment`)+ under the `notfair://` scheme — or alias both schemes during the+ rename window — before this version reaches users. As of this+ changelog entry the live server still publishes under+ `adsagent://playbooks/*`, so playbook fetches via `ReadMcpResourceTool`+ will fail until the server-side rename ships.++### Breaking — pre-0.19 users without migrated config++- The auto-migration shipped in 0.15.0 (legacy `.adsagent` paths →+ `.notfair` paths) is gone. Users who first installed the plugin+ before 0.15.0 AND never invoked any google-ads skill on a+ 0.15.x–0.22.x version will, on upgrade to 0.23.0, find their saved+ `accountId` and data files invisible to the plugin. Resolution:+ rename the legacy global directory (`~/.adsagent` → `~/.notfair`),+ the legacy project config file (`.adsagent.json` → `.notfair.json`),+ and the legacy project data dir if any (`.adsagent/` → `.notfair/`)+ manually, or simply re-run the `/google-ads` onboarding to save a+ fresh `accountId`. One-time-per-machine fix.++---+## [0.22.0] — 2026-05-15### Added — opt-in OpenClaw cron publisherdiff --git a/CLAUDE.md b/CLAUDE.mdindex 79f21fc9..88e15337 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -34,16 +34,9 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit- Never add internal-only notes, secrets, credentials, dev scratch files, or references to private infra. This repo is public.- Test skills end-to-end before shipping — `SKILL.md` frontmatter (`name`, `description`, triggers) is how Claude decides to invoke them; typos or stale descriptions break discovery.-## Branding: NotFair going forward+## Branding: NotFair-The product is **NotFair**. All new user-facing text, documentation, skill descriptions, and config namespaces must use NotFair / `notfair.co` / `.notfair/` / `mcp__notfair__*`. Do not introduce new references to "AdsAgent", "adsagent", `.adsagent/`, `mcp__adsagent__*`, `adsagent.org`, or the `adsagent://` URI scheme in new code or new docs.--Existing legacy references that are still in the codebase fall into two categories:--1. **Load-bearing compatibility code** — the `.adsagent/` → `.notfair/` filesystem migration in `google-ads/shared/preamble.md` Step 1, the `mcp__adsagent__*` prefix detection in Step 3, and the matching signal detection in `gemini/SKILL.md`. These are doing real work for users upgrading from pre-0.16 plugins. Do not remove without an explicit deprecation plan.-2. **Historical record** — `CHANGELOG.md` entries describing past renames. Never rewrite history.--If you find a non-load-bearing, non-historical `adsagent` reference in active skill text or docs, scrub it.+The product is **NotFair**. All user-facing text, documentation, skill descriptions, and config namespaces use NotFair / `notfair.co` / `.notfair/` / `mcp__notfair__*`. The prior brand has been fully removed from this repo — do not reintroduce any of its strings (names, config paths, MCP prefixes, URI schemes, or domains) in new code, new docs, or rewrites of existing files. The only allowed "legacy" references in active code are the `mcp__notfair__*` prefix and `.notfair.json` config (these reflect the more recent NotFair → NotFair-GoogleAds namespace split, not the older rebrand).## When adding or modifying a skill@@ -63,5 +56,4 @@ Semantic-ish: bump patch for skill additions / fixes, minor for new categories o## Related repos-- `adsagent-plugin/` (sibling dir, separate public repo) — a smaller Google-Ads-only plugin. Some skills are mirrored there; don't confuse it with this one.- NotFair MCP server — private, powers the Google Ads tool calls the skills depend on.diff --git a/README.md b/README.mdindex 5bd8e7c0..173219c2 100644--- a/README.md+++ b/README.md@@ -281,7 +281,7 @@ Toprank skills reference external tools using the `~~category` placeholder patte| Category | Placeholder | Default Server | Alternatives ||----------|-------------|---------------|--------------|-| Google Ads | `~~google-ads` | [NotFair-GoogleAds MCP](https://notfair.co) (legacy `mcp__notfair__*` and `mcp__adsagent__*` still detected during the rename window) | Google Ads MCP (`mcp__google_ads_mcp__*`) |+| Google Ads | `~~google-ads` | [NotFair-GoogleAds MCP](https://notfair.co) (legacy `mcp__notfair__*` still detected during the rename window) | Google Ads MCP (`mcp__google_ads_mcp__*`) || Meta Ads | `~~meta-ads` | [NotFair-MetaAds MCP](https://notfair.co) | Any Meta Marketing API MCP (`mcp__.*meta.*ads__*`) || Search Console | `~~search-console` | gcloud CLI + Search Console API | Any GSC-compatible MCP server || CMS | `~~cms` | Direct API (WordPress REST, Strapi, Contentful, Ghost) | Any CMS MCP server |diff --git a/VERSION b/VERSIONindex 21574090..ca222b7c 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.22.0+0.23.0diff --git a/gemini/SKILL.md b/gemini/SKILL.mdindex 932ddb5c..596ac09f 100644--- a/gemini/SKILL.md+++ b/gemini/SKILL.md@@ -84,9 +84,9 @@ Determine what kind of changes are being reviewed. Check in this order:### 2a — Check for Google Ads changesLook for signs of Ads-related work in the current conversation context:-- Recent MCP tool calls to `mcp__notfair__*` (or legacy `mcp__adsagent__*`) or `mcp__google_ads_mcp__*`+- Recent MCP tool calls to `mcp__notfair__*` or `mcp__google_ads_mcp__*`- Discussion of campaigns, keywords, bids, budgets, ad copy, negative keywords-- Files like `.notfair/change-log.json` (or legacy `.adsagent/change-log.json`) or Ads-related config changes+- Files like `.notfair/change-log.json` or Ads-related config changesIf found, set `CHANGE_TYPE=google-ads`.diff --git a/google-ads/audit/SKILL.md b/google-ads/audit/SKILL.mdindex 0c7c6735..ebd318f5 100644--- a/google-ads/audit/SKILL.md+++ b/google-ads/audit/SKILL.md@@ -34,7 +34,7 @@ Read `../shared/policy-registry.json`. For each entry where `last_verified + sta## Phase 1 — Pull the audit dataset-Use a single `runScript` call with `ads.gaqlParallel` to fan out the queries an audit needs. The server's `adsagent://playbooks/audit-account` resource has a battle-tested baseline; extend it with what your specific question needs.+Use a single `runScript` call with `ads.gaqlParallel` to fan out the queries an audit needs. The server's `notfair://playbooks/audit-account` resource has a battle-tested baseline; extend it with what your specific question needs.You decide the exact GAQL shape, but a defensible audit needs to see, at minimum:diff --git a/google-ads/manage/SKILL.md b/google-ads/manage/SKILL.mdindex 1257379f..072f3c29 100644--- a/google-ads/manage/SKILL.md+++ b/google-ads/manage/SKILL.md@@ -54,7 +54,7 @@ What does have to be true on every turn:- **Reads go through `runScript`** with `ads.gaql` / `ads.gaqlParallel` — fan out, correlate in-script, return summarized JSON. Cast a wide net on the first call.- **Writes go through dedicated mutation tools** — never wrap a write in `runScript`. Every write returns a `changeId` for `undoChange` within 7 days.- **Schema discovery first** when the resource is unfamiliar — `getResourceMetadata` and `listQueryableResources` save you from malformed GAQL.-- **The MCP server's playbooks** (`adsagent://playbooks/audit-account`, `adsagent://playbooks/explain-regression`) are battle-tested starting queries. Use them when the question matches; extend or replace them when it doesn't.+- **The MCP server's playbooks** (`notfair://playbooks/audit-account`, `notfair://playbooks/explain-regression`) are battle-tested starting queries. Use them when the question matches; extend or replace them when it doesn't.## Tool surface (capabilities, not enumeration)diff --git a/google-ads/shared/analysis-principles.md b/google-ads/shared/analysis-principles.mdindex 0571e0c2..84e4bf38 100644--- a/google-ads/shared/analysis-principles.md+++ b/google-ads/shared/analysis-principles.md@@ -16,7 +16,7 @@ When the data is too thin to support a recommendation, say so explicitly and pro## High-level approach (you decide the specifics)-Trust your own diagnostic judgment on tool sequencing, GAQL shape, and which surfaces to correlate. You know how to use `runScript` + `ads.gaqlParallel` to fan out, and the MCP server's playbooks (`adsagent://playbooks/*`) give you battle-tested starting queries. Lean on them; deviate when the question warrants. The references in each skill are calibration data when you need an anchor — not mandatory reading or decision trees to follow step by step.+Trust your own diagnostic judgment on tool sequencing, GAQL shape, and which surfaces to correlate. You know how to use `runScript` + `ads.gaqlParallel` to fan out, and the MCP server's playbooks (`notfair://playbooks/*`) give you battle-tested starting queries. Lean on them; deviate when the question warrants. The references in each skill are calibration data when you need an anchor — not mandatory reading or decision trees to follow step by step.What does need to be true on every analysis:diff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.mdindex 6f396f47..76738b9f 100644--- a/google-ads/shared/preamble.md+++ b/google-ads/shared/preamble.md@@ -1,6 +1,6 @@# Google Ads Shared Preamble-Every google-ads skill reads this before doing anything else. It handles updates, legacy-path migration, MCP detection, config resolution, and onboarding in one place — so individual skills don't repeat this logic.+Every google-ads skill reads this before doing anything else. It handles updates, MCP detection, config resolution, and onboarding in one place — so individual skills don't repeat this logic.## Step 0: Check for toprank updates@@ -16,54 +16,7 @@ If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded frIf neither: continue to Step 1 silently.-## Step 1: Migrate legacy `.adsagent` paths (one-time, silent)--The MCP server moved from AdsAgent to NotFair. Existing users may have config and data under `.adsagent`-named paths from before the rename — move it to the new `.notfair` namespace before reading config so all subsequent steps see consistent state. If the new path already exists, **do not overwrite** — flag the conflict and stop.--Run this as a single bash block (atomic `mv`, refuses to overwrite, no-op when nothing to migrate):--```bash-_NF_MIGRATED=()-_NF_CONFLICTS=()--_nf_move() {- local src="$1" dst="$2"- if [ -e "$src" ] || [ -L "$src" ]; then- if [ -e "$dst" ] || [ -L "$dst" ]; then- _NF_CONFLICTS+=("$src → $dst (target already exists)")- else- mv "$src" "$dst" && _NF_MIGRATED+=("$src → $dst")- fi- fi-}--# Global config + data directory-_nf_move "$HOME/.adsagent" "$HOME/.notfair"--# Project-level config + data directory (in the current working directory)-_nf_move "$(pwd)/.adsagent.json" "$(pwd)/.notfair.json"-_nf_move "$(pwd)/.adsagent" "$(pwd)/.notfair"--# Claude-project-level config (slug = CWD with '/' replaced by '-')-_NF_SLUG=$(pwd | sed 's|/|-|g')-_nf_move "$HOME/.claude/projects/$_NF_SLUG/adsagent.json" \- "$HOME/.claude/projects/$_NF_SLUG/notfair.json"--if [ ${#_NF_MIGRATED[@]} -gt 0 ]; then- echo "MIGRATED:"- for m in "${_NF_MIGRATED[@]}"; do echo " - $m"; done-fi-if [ ${#_NF_CONFLICTS[@]} -gt 0 ]; then- echo "CONFLICTS:"- for c in "${_NF_CONFLICTS[@]}"; do echo " - $c"; done-fi-```--- **Output contains `MIGRATED:`** — briefly tell the user "Migrated your AdsAgent config to the new NotFair location (`.adsagent` → `.notfair`)", then continue to Step 2.-- **Output contains `CONFLICTS:`** — both the legacy and new paths exist for at least one item; the user has partial state from a previous migration attempt. Show the conflicts and tell the user to manually reconcile (typically: inspect both, keep the newer `.notfair` copy, delete the stale `.adsagent` copy). **Stop here** until they resolve it — running with split state will silently lose writes.-- **Empty output** — nothing to migrate; continue to Step 2 silently.--## Step 2: Resolve config+## Step 1: Resolve configRead config from three locations and merge fields (first non-null, non-empty-string value wins per field):@@ -86,28 +39,27 @@ Create `{data_dir}` if it doesn't exist. Ensure `~/.notfair/` also exists (neede**Important:** If using project-local storage (`.notfair/`), ensure `.notfair.json` and `.notfair/` are in the project's `.gitignore` — they contain business-sensitive data that should not be committed.-Continue to Step 3 (MCP detection always runs).+Continue to Step 2 (MCP detection always runs).-## Step 3: MCP Server Detection+## Step 2: MCP Server DetectionAlways verify that a Google Ads MCP server is available — the MCP server could be down, unauthorized, or misconfigured even with a saved accountId.-1. Check for NotFair tools. The MCP server may be exposed under several different tool-name prefixes depending on the host (across the AdsAgent → NotFair → NotFair-GoogleAds renames, multiple prefixes may briefly coexist):+1. Check for NotFair tools. The MCP server may be exposed under several different tool-name prefixes depending on the host (across the NotFair → NotFair-GoogleAds namespace split, multiple prefixes may briefly coexist):- `mcp__NotFair-GoogleAds__*` / `mcp__notfair_googleads__*` / `mcp__NotFair_GoogleAds__*` — Claude Code CLI (toprank plugin default, current; exact form depends on Claude Code's key sanitization)- `mcp__claude_ai_NotFairGoogleAds__*` — Claude Desktop / claude.ai plugin connector (current)- `mcp__notfair__*` / `mcp__claude_ai_NotFair__*` — pre-0.16.0 plugin (legacy NotFair prefix, before the GoogleAds namespace split)- - `mcp__adsagent__*` / `mcp__claude_ai_AdsAgent__*` — pre-0.15.0 plugin (legacy AdsAgent prefix)- - any other prefix matching `mcp__.*([Nn]ot[Ff]air|[Aa]ds[Aa]gent)__` (future hosts)+ - any other prefix matching `mcp__.*[Nn]ot[Ff]air.*__` (future hosts)- **How to detect:** scan your available tool list for any tool whose name ends in `listConnectedAccounts`. Take everything before `listConnectedAccounts` as the detected prefix. If multiple candidates exist, prefer current over legacy: any `NotFair-GoogleAds`/`NotFairGoogleAds`/`notfair_googleads` variant > `mcp__notfair__` / `mcp__claude_ai_NotFair__` > `mcp__adsagent__` / `mcp__claude_ai_AdsAgent__` > any other match. Call `listConnectedAccounts` using that detected prefix, and save both the result and the prefix itself for reuse in Steps 4 and 5.+ **How to detect:** scan your available tool list for any tool whose name ends in `listConnectedAccounts`. Take everything before `listConnectedAccounts` as the detected prefix. If multiple candidates exist, prefer current over legacy: any `NotFair-GoogleAds`/`NotFairGoogleAds`/`notfair_googleads` variant > `mcp__notfair__` / `mcp__claude_ai_NotFair__` > any other match. Call `listConnectedAccounts` using that detected prefix, and save both the result and the prefix itself for reuse in Steps 3 and 4.- **Legacy-prefix migration nudge:** if the chosen prefix is a legacy `mcp__notfair__` / `mcp__adsagent__` (or their `claude_ai_*` variants) and no current NotFair-GoogleAds variant is visible, briefly tell the user once:+ **Legacy-prefix migration nudge:** if the chosen prefix is a legacy `mcp__notfair__` (or its `claude_ai_*` variant) and no current NotFair-GoogleAds variant is visible, briefly tell the user once:> Detected a legacy MCP server registration. The plugin's MCP server has been renamed to NotFair-GoogleAds — please **restart Claude Code** to pick up the new server registration. Continuing with the legacy server for this session.Then proceed normally — the legacy server still works (it points at the new `notfair.co/api/mcp/google_ads` endpoint after the recent rename); only the tool-name prefix is stale.-2. If no NotFair/AdsAgent variant exists, check for Google's official MCP: look for tools matching `mcp__google_ads_mcp__*`.+2. If no NotFair variant exists, check for Google's official MCP: look for tools matching `mcp__google_ads_mcp__*`.3. If none exists, lead with the connection CTA — don't bury it in troubleshooting:> **Connect to NotFair to manage Google Ads.**@@ -123,11 +75,11 @@ Always verify that a Google Ads MCP server is available — the MCP server couldStop here until the MCP server is available.-If `accountId` was already resolved in Step 2, skip to Step 5. Otherwise, continue to Step 4.+If `accountId` was already resolved in Step 1, skip to Step 4. Otherwise, continue to Step 3.-## Step 4: Onboarding (only if accountId is missing)+## Step 3: Onboarding (only if accountId is missing)-Use the `listConnectedAccounts` result from Step 3 (do not call it again):+Use the `listConnectedAccounts` result from Step 2 (do not call it again):1. **One account** → save automatically to the highest-priority config file that already exists (project > claude-project > global; if none exist yet, save to `~/.notfair/config.json`), tell the user which was selected2. **Multiple accounts** → show numbered list, ask user to pick, save choice to the same location@@ -144,17 +96,16 @@ If the user explicitly asks to switch accounts, run `listConnectedAccounts`, let- **Project** → write `accountId` to `.notfair.json` in the current working directory (create the file if needed)- **Global** → write `accountId` to `~/.notfair/config.json`-## Step 5: Calling tools+## Step 4: Calling tools-Use whichever MCP server prefix was detected in Step 3:+Use whichever MCP server prefix was detected in Step 2:- **NotFair-GoogleAds MCP via Claude Code CLI (current):** `mcp__NotFair-GoogleAds__<toolName>` (or whatever sanitized form Claude Code emits — `mcp__notfair_googleads__`, `mcp__NotFair_GoogleAds__`, etc.)- **NotFair-GoogleAds MCP via Claude Desktop / claude.ai plugin (current):** `mcp__claude_ai_NotFairGoogleAds__<toolName>`- **Legacy NotFair MCP (pre-0.16.0 plugin):** `mcp__notfair__<toolName>` / `mcp__claude_ai_NotFair__<toolName>`-- **Legacy AdsAgent MCP (pre-0.15.0 plugin):** `mcp__adsagent__<toolName>` / `mcp__claude_ai_AdsAgent__<toolName>`- **Google's official MCP:** `mcp__google_ads_mcp__<toolName>`-Always call tools under the exact prefix detected in Step 3 — do not hardcode any prefix. Pass `accountId` from the resolved config (Step 2) to every tool call (except `listConnectedAccounts`).+Always call tools under the exact prefix detected in Step 2 — do not hardcode any prefix. Pass `accountId` from the resolved config (Step 1) to every tool call (except `listConnectedAccounts`).### Reads vs. writes@@ -164,6 +115,6 @@ The MCP server's own instructions are the canonical guide and are surfaced to th- **Mutations** go through dedicated write tools (`pauseKeyword`, `updateBid`, `createCampaign`, etc.). Never wrap a mutation in `runScript`.- **Schema discovery** (`getResourceMetadata`, `listQueryableResources`) is the right call before writing GAQL against an unfamiliar resource.-The server also publishes ready-to-use playbooks as MCP resources — `adsagent://playbooks/audit-account` and `adsagent://playbooks/explain-regression`. Fetch them when the user asks the matching question rather than rediscovering the query shape.+The server also publishes ready-to-use playbooks as MCP resources — `notfair://playbooks/audit-account` and `notfair://playbooks/explain-regression`. Fetch them when the user asks the matching question rather than rediscovering the query shape.Config is loaded. Hand control back to the invoking skill.diff --git a/test/install.test.sh b/test/install.test.shindex d777abf1..5e6ef98a 100755--- a/test/install.test.sh+++ b/test/install.test.sh@@ -159,8 +159,6 @@ for skill in manage audit copy; do"$skill references shared preamble"assert_not_contains "$REPO_ROOT/google-ads/$skill/SKILL.md" "mcp__notfair__listConnectedAccounts" \"$skill does not inline MCP detection (notfair prefix)"- assert_not_contains "$REPO_ROOT/google-ads/$skill/SKILL.md" "mcp__adsagent__listConnectedAccounts" \- "$skill does not inline MCP detection (legacy adsagent prefix)"done# SEO skills that need GSC reference the shared preamble