Open-source SEO, GEO, and marketing skills for AI agents.
feat(plugin): release unified MCP and portable skills v0.27.4
Yuting Zhong7b9d5d7d933f
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 9fe0eac8..38c23afa 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.2"+ "version": "0.27.4"},"plugins": [{"name": "notfair","source": "./","description": "Operate Google, Meta, X, and LinkedIn Ads; analyze Search Console and GA4; and run open-source SEO, GEO, and content workflows.",- "version": "0.27.2",+ "version": "0.27.4","author": {"name": "NotFair","url": "https://notfair.co"diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 23cd6499..f7f84cf6 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.2",+ "version": "0.27.4","description": "The official ads, analytics, SEO, and GEO plugin from NotFair. Operate Google, Meta, X, and LinkedIn Ads; 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 6903c11b..64e1ced1 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.2",+ "version": "0.27.4","description": "The official ads, analytics, SEO, and GEO plugin from NotFair.","author": {"name": "NotFair",@@ -17,7 +17,7 @@"seo"],"skills": "./skills/",- "mcpServers": "./mcp.json",+ "mcpServers": "./.mcp.json","interface": {"displayName": "NotFair","shortDescription": "Operate ads and analyze search performance.",diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.jsonindex 75c4caa6..840484df 100644--- a/.cursor-plugin/plugin.json+++ b/.cursor-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "notfair","displayName": "NotFair",- "version": "0.27.2",+ "version": "0.27.4","description": "Optimize Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Search Console, Google Analytics 4, and GoHighLevel with live data, open-source marketing skills, and approval-gated writes.","author": {"name": "NotFair"diff --git a/.github/workflows/mcp-registry-publish.yml b/.github/workflows/mcp-registry-publish.ymlindex b813dbf7..808d956b 100644--- a/.github/workflows/mcp-registry-publish.yml+++ b/.github/workflows/mcp-registry-publish.yml@@ -1,15 +1,15 @@-name: Publish Google Ads MCP registry metadata+name: Publish NotFair MCP registry metadataon:push:branches: [main]paths:- - "server-google-ads.json"+ - "server.json"- ".github/workflows/mcp-registry-publish.yml"workflow_dispatch:concurrency:- group: mcp-registry-google-ads+ group: mcp-registry-notfaircancel-in-progress: falsejobs:@@ -35,10 +35,10 @@ jobs:chmod +x mcp-publisher- name: Validate registry metadata- run: ./mcp-publisher validate server-google-ads.json+ run: ./mcp-publisher validate server.json- name: Authenticate with GitHub OIDCrun: ./mcp-publisher login github-oidc- name: Publish registry metadata- run: ./mcp-publisher publish server-google-ads.json+ run: ./mcp-publisher publish server.jsondiff --git a/AGENTS.md b/AGENTS.mdindex 917d86f8..f41698b8 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -98,7 +98,7 @@ Skills under `seo/`, `paid-ads/`, `google-ads/`, `meta-ads/`, `analytics/`, `gem## External dependencies-- **Universal NotFair MCP** — `https://notfair.co/api/mcp/notfair`, OAuth. The plugin registers this single connection for Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Search Console, Google Analytics, and GoHighLevel. Its tools carry platform prefixes such as `google_ads_`, `meta_ads_`, and `search_console_`; verify the requested platform is connected before claiming live access.+- **Universal NotFair MCP** — `https://notfair.co/api/mcp/notfair`, OAuth. The plugin registers this single connection for Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Search Console, Google Analytics, and GoHighLevel. Read [`docs/mcp-connection.md`](docs/mcp-connection.md) before live work. Use the connected server's current instructions and capability descriptions to select tools and verify workspace/platform access; do not prescribe tool names or call sequences in skills.- **Platform connections** — each live skill still requires its corresponding account or property to be connected inside the selected NotFair workspace. A universal MCP session does not imply that every platform is connected.- **Google Gemini API key** — required for `gemini`.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1771b47d..07cc74e7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -21,6 +21,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).### Changed+- **Skills follow live capabilities (v0.27.4).** Removed fixed MCP tool catalogs, forced call sequences, assumed limits and rollback guarantees. Account-list requests stay scoped, and SEO uses existing connectors without mandatory gcloud setup.++- **Compact MCP migration completed (v0.27.3).** All plugin hosts use one `NotFair` connection at `https://notfair.co/api/mcp/notfair`. Skills now discover capabilities with `search` and use `executeRead` or `execute`, checking workspace platform access first. The registry workflow publishes only `server.json`; obsolete Google Ads and Meta Ads registry manifests are removed. The README and install guide include upgrade and reauthorization instructions. Older entries below describe historical releases, not current connection configuration.+- **Canonical all-platform MCP endpoint (v0.27.2).** Updated Cursor, Codex, Claude, Gemini, Agent Plugins, MCP Registry metadata, tests, and public documentation to advertise `https://notfair.co/api/mcp/notfair`. The backward-compatible legacy route remains supported but is no longer shown to new users.- **One-command universal MCP onboarding (v0.27.0).** Replaced the six bundled platform server registrations with one `NotFair` MCP connection, now advertised at `https://notfair.co/api/mcp/notfair`. Codex and Claude now need one OAuth grant; workspaces enabled in the staged Google-first rollout connect Google Ads during that flow, and every supported platform remains isolated behind explicit tool prefixes such as `google_ads_`, `meta_ads_`, and `search_console_`.- **Repository renamed to `nowork-studio/notfair-plugin`.** Active clone, install, update-check, package metadata, and source links now use the new GitHub repository name. The plugin name and `/notfair:*` command namespace remain unchanged.diff --git a/CLAUDE.md b/CLAUDE.mdindex 665527c5..9dcfa646 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -48,7 +48,7 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit## Branding: NotFair-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. Dedicated platform-prefixed NotFair namespaces may remain in compatibility guidance, but the installed plugin's current default is the universal `NotFair` server.+The product is **NotFair**. All user-facing text, documentation, skill descriptions, and config namespaces use NotFair / `notfair.co` / `.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 installed plugin uses one compact `NotFair` server at `https://notfair.co/api/mcp/notfair`. Follow `docs/mcp-connection.md` for connection guidance. Keep skills focused on the user's objective and domain knowledge; use the live server's instructions and schemas for tool selection rather than maintaining tool catalogs or forced call sequences.## When adding or modifying a skilldiff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.mdindex 44eef9eb..4ba6b53c 100644--- a/INSTALL_FOR_AGENTS.md+++ b/INSTALL_FOR_AGENTS.md@@ -83,7 +83,9 @@ Read `AGENTS.md` at the repo root. It contains the full intent → skill routing## Step 4 — Connect external services-The plugin registers one universal NotFair MCP server at `https://notfair.co/api/mcp/notfair`. The Codex install command above explicitly starts its native OAuth flow; other hosts prompt on install or first use. The user signs in once and selects a NotFair workspace. During the staged Google-first rollout, enabled workspaces also connect Google Ads when they do not already have an active account. Google Ads, Meta Ads, X Ads, LinkedIn Ads, Search Console, Google Analytics, and GoHighLevel then appear as platform-prefixed tools through that one connection.+The plugin registers one universal NotFair MCP server at `https://notfair.co/api/mcp/notfair`. The Codex install command above explicitly starts its native OAuth flow; other hosts prompt on install or first use. The user signs in once and selects a NotFair workspace. Follow any account setup guidance in the OAuth flow; connect additional platforms inside the selected workspace. Google Ads, Meta Ads, X Ads, LinkedIn Ads, Search Console, Google Analytics, and GoHighLevel are available as capabilities through that one connection.++Follow [`docs/mcp-connection.md`](docs/mcp-connection.md) and the live server's instructions to discover the capabilities needed for the task and verify platform access. When upgrading, replace manually configured per-platform entries with the single `NotFair` connection and reauthorize when prompted.NotFair skills depend on external APIs. Walk the user through whichever they need:diff --git a/README.md b/README.mdindex 0c714695..f1159894 100644--- a/README.md+++ b/README.md@@ -208,20 +208,23 @@ Marketing work gets unreliable when every request goes through the same vague pr## Live data and integrations-Some skills work entirely from a repository, URL, or supplied export. Live account analysis uses one OAuth-connected [universal NotFair MCP](https://notfair.co/api/mcp/notfair). The plugin registers that connection automatically. During the staged Google-first rollout, enabled workspaces connect Google Ads in the same OAuth flow; every other platform becomes available after it is connected in the selected NotFair workspace.+Some skills work entirely from a repository, URL, or supplied export. Live account analysis uses one OAuth-connected [universal NotFair MCP](https://notfair.co/api/mcp/notfair). The plugin registers exactly one server named **NotFair**, shared by every supported platform.++The agent chooses tools from the live server's instructions and capability descriptions. Skills supply marketing workflows and evidence standards without hardcoding MCP tool names or call sequences. See [the connection and upgrade guide](docs/mcp-connection.md) for manual configuration and migration from older per-platform connections. Each platform becomes available after it is connected in the NotFair workspace selected during OAuth. Follow any account setup guidance returned by the server.| Data source | Used for | Connection ||---|---|---|-| **Google Search Console** | Search performance, queries, pages, indexing, URL inspection, and sitemaps | Universal NotFair MCP via `search_console_` tools |-| **Google Analytics 4** | Acquisition, engagement, landing pages, events, conversions, realtime, and measurement configuration | Universal NotFair MCP via `google_analytics_` tools |-| **Google Ads** | Campaign performance, search terms, bids, budgets, keywords, and change history | Universal NotFair MCP via `google_ads_` tools |-| **Meta Ads** | Facebook and Instagram campaigns, ad sets, creatives, and insights | Universal NotFair MCP via `meta_ads_` tools |-| **X Ads** | Campaigns, line items, performance, targeting, promoted posts, audiences, and approved mutations | Universal NotFair MCP via `x_ads_` tools |-| **LinkedIn Ads** | Campaign groups, campaigns, creatives, analytics, targeting, conversions, and leads | Universal NotFair MCP via `linkedin_ads_` tools |+| **Google Search Console** | Search performance, queries, pages, indexing, URL inspection, and sitemaps | One NotFair connection |+| **Google Analytics 4** | Acquisition, engagement, landing pages, events, conversions, realtime, and measurement configuration | One NotFair connection |+| **Google Ads** | Campaign performance, search terms, bids, budgets, keywords, and change history | One NotFair connection |+| **Meta Ads** | Facebook and Instagram campaigns, ad sets, creatives, and insights | One NotFair connection |+| **X Ads** | Campaigns, line items, performance, targeting, promoted posts, audiences, and approved mutations | One NotFair connection |+| **LinkedIn Ads** | Campaign groups, campaigns, creatives, analytics, targeting, conversions, and leads | One NotFair connection |+| **GoHighLevel** | Connected CRM and downstream lead workflows | One NotFair connection || **CMS platforms** | Content and SEO-field review in WordPress, Strapi, Contentful, or Ghost | Platform API or compatible MCP || **Google Gemini** | Cross-model review | Gemini API key |-Google Ads, Meta Ads, X Ads, and LinkedIn Ads use explicit, bounded mutation tools. Search Console and GA4 also expose narrow configuration writes with approval and read-back rules. TikTok, Amazon, and ChatGPT Ads remain planning or export-review workflows unless the current agent session exposes a verified connector.+Supported account operations come from the live connection. Changes must stay within the user's authorization and be verified against the resulting account state. TikTok, Amazon, and ChatGPT Ads remain planning or export-review workflows unless the current agent session exposes a verified connector.## Privacy and supportdiff --git a/VERSION b/VERSIONindex 3edc695d..9f222923 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.27.2+0.27.4diff --git a/analytics/google-analytics/SKILL.md b/analytics/google-analytics/SKILL.mdindex dc44dfc7..2e016558 100644--- a/analytics/google-analytics/SKILL.md+++ b/analytics/google-analytics/SKILL.md@@ -6,17 +6,17 @@ argument-hint: "<property, date range, metric, or GA4 question>"# Google Analytics-Read `../shared/operating-contract.md`. Use the `google_analytics_` tools on the universal NotFair MCP as the source of truth.+Read `../shared/operating-contract.md`. Use the live connector's instructions and schemas to choose tools for the task.## Select the property and question-1. Resolve `~~google-analytics` to the actual GA4 connector and inspect its current tools. Confirm access with `listProperties` or the equivalent harmless property-list read.+1. Resolve `~~google-analytics` to the actual GA4 connector and inspect its current tools. Confirm access and the available properties from live data.2. Select the exact `properties/123456789` resource returned by the connector. Never substitute a `G-` measurement ID or Google account ID.3. Define the business question, primary metric, conversion or key-event definition, property timezone, date range, and comparison window. If the platform is missing or unauthorized, direct the user to reconnect the universal NotFair plugin and stop before claiming live data.## Pull decision-grade evidence-Use `runScript` for multi-report analysis and correlation. Fan out the smallest useful set of reports across channel, source/medium, campaign, landing page, device, geography, or event; use the typed `runReport`, realtime, or metadata reads for a single narrow task.+Pull the smallest useful set of reports across channel, source/medium, campaign, landing page, device, geography, or event. Choose available reporting capabilities and batch related reads when supported and useful.- Compare complete equivalent periods and show absolute values plus deltas.- Use metadata before guessing an unfamiliar dimension/metric pair. Respect the current API's dimension, metric, fan-out, and quota limits exposed by the tool.@@ -29,11 +29,11 @@ Lead with what changed, where it changed, the evidence-backed likely driver, con## Change measurement configuration-Use only dedicated mutation tools for supported key-event and custom-dimension changes. Show the exact property, current state, proposed state, downstream reporting impact, and rollback before asking for approval.+Use currently available capabilities for supported key-event and custom-dimension changes. Show the exact property, current state, proposed state, downstream reporting impact, and rollback before asking for approval.- Creating and deleting a key event are reversible counterparts when the same event definition is available.- Archiving a custom dimension is irreversible in GA4 and its parameter name cannot be reused. Require explicit approval that names the property and dimension before archiving.-- Never wrap a mutation in `runScript`.+- Respect the read/write boundary described by the live capability.- Confirm success from returned before/after evidence or a fresh configuration read; report partial failures without retrying blindly.Do not describe a report as saved or a dashboard as published unless the connected tool explicitly supports that operation and confirms it.diff --git a/analytics/search-console/SKILL.md b/analytics/search-console/SKILL.mdindex c57df339..19c1dec5 100644--- a/analytics/search-console/SKILL.md+++ b/analytics/search-console/SKILL.md@@ -6,17 +6,17 @@ argument-hint: "<property, URL, query, date range, or sitemap>"# Google Search Console-Read `../shared/operating-contract.md`. Use the `search_console_` tools on the universal NotFair MCP as the source of truth. For a full-site SEO audit that also needs crawling and on-page analysis, hand off to `/notfair:seo-analysis` after confirming access.+Read `../shared/operating-contract.md`. Use the live connector's instructions and schemas to choose tools for the task. For a full-site SEO audit that also needs crawling and on-page analysis, hand off to `/notfair:seo-analysis` after confirming access.## Select the exact property-1. Resolve `~~search-console` to the actual Search Console connector and inspect its current tools. Call `listProperties` or the equivalent harmless read before selecting a site.+1. Resolve `~~search-console` to the actual Search Console connector and inspect its current tools. Use live property information to identify the intended site.2. Use the exact verified property form returned by the connector: `sc-domain:example.com` and `https://example.com/` are different properties.3. Define the search type, complete date window, comparison window, dimensions, and business question. If the platform is missing or unauthorized, direct the user to reconnect the universal NotFair plugin and stop before claiming live data.## Analyze organic performance-Use `runScript` for correlated read-only work across totals, queries, pages, countries, and devices. Batch related Search Analytics requests in one script when possible. Use specialized reads for a single report, property list, one URL inspection, or sitemap inventory.+Correlate totals, queries, pages, countries, and devices as needed for the question. Choose available reporting capabilities; batch related reads when supported and useful, and use a narrow read for a single property, URL, or sitemap.- Query totals without the `query` dimension when reconciling property-level clicks and impressions. Anonymized low-volume queries make query rows incomplete by design.- Finalized data normally lags recent dates; label fresh `all` data as provisional.@@ -29,6 +29,6 @@ Lead with the largest material gain or loss, affected queries/pages, evidence-ba## Manage sitemaps safely-Use dedicated `submitSitemap` or `deleteSitemap` tools only after showing the exact verified property and sitemap URL and obtaining approval. Confirm the sitemap belongs to the selected property and is fetchable before submission when possible.+Submit or remove a sitemap through a supported capability only after showing the exact verified property and sitemap URL and obtaining approval. Confirm the sitemap belongs to the selected property and is fetchable before submission when possible.Submission and deletion are reversible counterparts, but deleting a submitted sitemap does not remove its URLs from Google's index. Never describe sitemap submission as an indexing guarantee. Confirm the resulting sitemap state from returned before/after evidence or a fresh list.diff --git a/analytics/shared/operating-contract.md b/analytics/shared/operating-contract.mdindex 9714c18f..da865ef6 100644--- a/analytics/shared/operating-contract.md+++ b/analytics/shared/operating-contract.md@@ -2,10 +2,10 @@Read this before using Search Console or Google Analytics data.-1. Discover the requested platform's actual tool prefix and harmlessly confirm the selected property. On the universal NotFair connector, call `listConnectedPlatforms` first and treat only the requested platform's prefixed tools as proof of access.+1. Follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md). Let the live connector determine tool selection and schemas; establish the requested platform and property from current connection data.2. State the property, timezone, source, date window, comparison window, dimensions, filters, and metric or conversion definition beside material findings.3. Prefer one broad, batched read over repeated narrow calls. Respect the tool's current quota and fan-out limits rather than copying limits from another platform.4. Separate observed facts, inferences, and recommendations. State freshness, sampling, thresholding, row caps, attribution, or tracking limitations.5. Keep Google Analytics, Search Console, and ad-platform attribution distinct. Reconcile their definitions before comparing values.-6. Use dedicated mutation tools only. Show the exact current/proposed state and rollback, then obtain explicit approval for sitemap or measurement-configuration changes.+6. Use capabilities whose current contract supports the requested change. Show the exact current/proposed state and rollback, then obtain explicit approval for sitemap or measurement-configuration changes.7. Confirm writes with returned before/after evidence or a fresh read. Never call an analysis, recommendation, or configuration draft published without live confirmation.diff --git a/docs/mcp-connection.md b/docs/mcp-connection.mdnew file mode 100644index 00000000..6b547a3c--- /dev/null+++ b/docs/mcp-connection.md@@ -0,0 +1,66 @@+# One NotFair MCP connection++Use one HTTP server named `NotFair` at `https://notfair.co/api/mcp/notfair`.+The connection is bound to the NotFair workspace selected during OAuth. Connect+Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Search Console, Google Analytics,+and GoHighLevel inside that workspace; do not add an MCP server per platform.++## Use the live capability descriptions++Choose tools from the connected server's current instructions, descriptions,+input schemas, and returned guidance. Use whatever discovery mechanism the host+or server provides when the needed capability is not already visible. These+skills describe the work and evidence required; they do not prescribe tool names,+MCP namespaces, operation IDs, argument shapes, batching limits, or call sequences.++Verify the requested workspace, platform, and account or property from live+connection information before claiming access. Follow returned setup guidance+when authorization or a platform connection is missing. Do not create a second+NotFair MCP connection to reach another platform.++Use the smallest set of reads that answers the user's question. An account-list+request needs an account list, not a full marketing audit. Preserve the user's+chosen scope and reuse existing context where it is sufficient.++For changes, establish the exact target and intended effect, stay within the+user's authorization, respect host and server approval controls, and verify the+result. Do not route writes through a read-only capability. Only claim success,+rollback support, stored history, or account access when the live result supports+it. If a capability is unavailable, explain that limitation rather than inventing+a tool or declaring the entire platform unsupported.++## Upgrade an existing installation++Update or reinstall the plugin through your host and start a new session. Keep+one `NotFair` connection at the URL above. If you manually added older per-platform+NotFair connections, remove those redundant host entries after the new connection+works. Plugin updates cannot remove entries you created outside the plugin.+Reauthorize the new connection when prompted; existing dedicated-platform tokens+do not grant the new `notfair` resource audience. Connect any missing platforms+inside the selected NotFair workspace.++For a manual host configuration:++```json+{+ "mcpServers": {+ "NotFair": {+ "type": "http",+ "url": "https://notfair.co/api/mcp/notfair"+ }+ }+}+```++## Host manifests++Claude Code and Codex load `.mcp.json`; Codex explicitly references that file in+`.codex-plugin/plugin.json`. Cursor and Agent Plugins hosts load `mcp.json`.+Gemini CLI embeds the same single connection in `gemini-extension.json`. These+configurations must stay in parity.++## Registry metadata++`server.json` is the single MCP Registry listing and the source used by the+registry publish workflow. Platform-specific registry manifests are retired;+they must not be reintroduced as plugin connections or publish targets.diff --git a/gemini-extension.json b/gemini-extension.jsonindex fe30e5bc..b5d3b683 100644--- a/gemini-extension.json+++ b/gemini-extension.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.2",+ "version": "0.27.4","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/assets/SKILL.md b/google-ads/assets/SKILL.mdindex 7f15c593..5c634d21 100644--- a/google-ads/assets/SKILL.md+++ b/google-ads/assets/SKILL.md@@ -16,7 +16,7 @@ Read `../shared/policy-registry.json` before PMax or policy-sensitive work. If i## Build from evidence, not filler-Pull the existing campaign, ad group, and asset coverage with `runScript` before recommending new assets. Use search terms, converting ads, landing-page content, approved offers, and customer language as source material. Do not infer ratings, pricing, guarantees, availability, or product attributes.+Pull the existing campaign, ad group, and asset coverage using available read capabilities before recommending new assets. Use search terms, converting ads, landing-page content, approved offers, and customer language as source material. Do not infer ratings, pricing, guarantees, availability, or product attributes.For each proposed asset, produce this reviewable manifest:@@ -35,9 +35,9 @@ Keep the brief deliberately varied: each concept should test a different motivat## Platform-aware execution- Validate copy and destination fields against the current connected tool metadata before creating anything. Do not trust memorized limits or silently truncate assets.-- Only create/link callouts, sitelinks, structured snippets, or image assets after the user approves the exact manifest. Use dedicated mutation tools, record the returned `changeId`, and read back the resulting entity.+- Only create/link callouts, sitelinks, structured snippets, or image assets after the user approves the exact manifest. Use a supported capability, record any operation identifiers returned, and verify the resulting entity.- Verify image ownership, landing-page rights, and policy-sensitive claims before an image asset is uploaded. A generated image is a production input, not proof that the claim in it is allowed.-- The current NotFair MCP surface can create/link supported asset-library types and can enable or pause PMax asset groups. It does **not** establish that it can compose or edit a PMax asset group. Check `tools/list` before promising that operation; otherwise deliver the PMax brief for completion in Google Ads.+- Check the live connection for the requested asset-library or PMax asset-group operation. If it is unavailable, deliver a brief for completion in Google Ads without claiming it was applied.## PMax brief@@ -53,5 +53,5 @@ For a PMax request, produce a cross-placement production brief rather than a gen1. Never publish an unsupported claim, a destination you did not validate, or an asset with unknown rights.2. Never call a production brief an uploaded asset. Separate `ready_for_review` from `published`.-3. Confirm scope and exact asset count before every write; mutations must be reversible through `undoChange` where supported.+3. Confirm scope and exact asset count before every write; check and explain the available reversal path.4. Defer bid, budget, keyword, and campaign-structure changes to `/google-ads`; defer RSA testing to `/google-ads-copy`.diff --git a/google-ads/audit/SKILL.md b/google-ads/audit/SKILL.mdindex a3a3b3c2..a1613415 100644--- a/google-ads/audit/SKILL.md+++ b/google-ads/audit/SKILL.md@@ -1,6 +1,6 @@---name: google-ads-audit-description: Google Ads account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other ads skills reuse. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to NotFair and hasn't run an audit before. Also trigger proactively when other ads skills detect that business-context.json is missing.+description: Google Ads account audit and business context setup. Use for account-health audits and business-context setup. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to NotFair and hasn't run an audit before.argument-hint: "<account name or 'audit my ads'>"---@@ -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 `notfair://playbooks/audit-account` resource has a battle-tested baseline; extend it with what your specific question needs.+Choose available read capabilities for the requested audit scope. Batch related reads where useful and supported; consult current server guidance for schemas and limits.You decide the exact GAQL shape, but a defensible audit needs to see, at minimum:@@ -52,9 +52,9 @@ You decide the exact GAQL shape, but a defensible audit needs to see, at minimumAggregate inside the script. Return summarized JSON, not raw rows. The agent narrates; the script does the math.-`getRecommendations` and `summarizeAccountSetup` are useful cross-checks against Google's own and the server's structural views — call them as a separate tool turn after the runScript pass when comparison would sharpen the report.+Use platform recommendations or account-setup diagnostics as optional cross-checks when available and relevant to the question.-If a critical query errors out (auth, schema), surface the error and stop — don't fall back to a degraded audit.+If a read fails, follow actionable recovery guidance. Clearly report missing evidence; continue independent findings only when the available data supports them.**Skip scoring entirely if** `totalSpend == 0` or `activeCampaigns == 0`. Go straight to business context.@@ -116,7 +116,7 @@ Structure: pulse metrics (3 lines, each with number + top contributor + fix poinEnd with a single closing line after the handoff to `/google-ads`:-> *Your audit history is saved to your NotFair account — view it at https://notfair.co.*+State where any audit artifacts were actually saved. Do not claim hosted audit history unless a live result confirms it.## Guardrailsdiff --git a/google-ads/copy/SKILL.md b/google-ads/copy/SKILL.mdindex e97a024c..e838da5d 100644--- a/google-ads/copy/SKILL.md+++ b/google-ads/copy/SKILL.md@@ -36,7 +36,7 @@ Ad strength optimizes for Google's diversity goals, not your conversion rate. Th## Pulling what to write from-Copy must be grounded in what already converts. One `runScript` with `ads.gaqlParallel` covers almost any copy job — fan out:+Copy must be grounded in what already converts. Choose available read capabilities for the evidence relevant to the requested copy:- `ad_group_ad` — current headlines, descriptions, ad-strength, per-ad clicks/CTR/conversions (the baseline to beat)- `keyword_view` — what's converting and which QS components are weak@@ -71,11 +71,11 @@ Google RSA: up to **15 headlines (30 chars max)** and **4 descriptions (90 chars## A/B testing — use the experiments framework-When the user wants to test, use the MCP server's experiment tooling rather than the old "deploy two paused ads side by side" pattern:--- **Ad-copy A/B** — `createAdVariationExperiment` is the dedicated tool for variation testing at the ad level. It manages the split, the lift comparison, and the read-back.-- **Larger creative shifts** (different angle, different persona target, different LP destination) — `createExperiment` + `addExperimentArms` + `scheduleExperiment`. Monitor with `listActiveExperiments` and `listExperimentAsyncErrors`. Decide endgame with `endExperiment`, `graduateExperiment`, or `promoteExperiment`.-- **Single ad-group, two variants, no traffic split** — paused-then-enabled twin ads in the same ad group is still acceptable for low-stakes copy iteration, but it has no statistical engine behind it. Prefer the experiment path when the decision matters.+When the user wants to test, define the hypothesis, traffic split, measurement,+and decision rule, then check which experiment capabilities the live connection+supports. Ad-copy tests and larger changes to audience or landing page may need+different designs. Running two ads side by side without a controlled split is+observational evidence; do not present it as a randomized experiment.Each variant must test a **meaningfully different angle** — not word swaps. "Trust & Expertise" vs. "Speed & Convenience" vs. "Price & Value" is a real test; "Call Today" vs. "Call Now" is noise.@@ -89,6 +89,6 @@ After a winner: pause the loser, then iterate against the winner. Never stop tes1. **Business context is non-negotiable.** No `business-context.json` / `personas` → recommend `/google-ads-audit` before writing.2. **Confirm before deploying.** Show the exact copy, character counts per asset, and pin positions. Get a yes, then push.-3. **Every write is undoable for 7 days** via `undoChange` (assuming the entity hasn't been modified since).+3. **Check reversibility.** Record the original state and only promise rollback when the current capability supports it.4. **Differentiate, don't imitate.** Generic copy that could belong to any competitor is a wasted ad slot.5. **Defer to `/google-ads`** for bid / budget / keyword work — this skill writes copy and runs creative experiments only.diff --git a/google-ads/copy/references/rsa-testing-lab.md b/google-ads/copy/references/rsa-testing-lab.mdindex 8c43203d..751366c7 100644--- a/google-ads/copy/references/rsa-testing-lab.md+++ b/google-ads/copy/references/rsa-testing-lab.md@@ -84,8 +84,8 @@ Default controlled structure:Preferred paths:-- Use `createAdVariationExperiment` for clean RSA asset tests.-- Use `createExperiment` + arms for broader ad+landing-page or structural tests.+- Use a supported ad-variation experiment for controlled RSA asset tests.+- Use a supported controlled experiment for broader ad, landing-page, or structural tests.- For very low-stakes / low-volume work, before/after can be acceptable, but report confounders.Minimum-read rules:diff --git a/google-ads/landing/SKILL.md b/google-ads/landing/SKILL.mdindex 2b79ec6d..f371452c 100644--- a/google-ads/landing/SKILL.md+++ b/google-ads/landing/SKILL.md@@ -27,9 +27,9 @@ When the question is about ad-to-page fit, high CTR / low CVR, LPX, or testing aFigure out which URLs to score. In priority order:1. **User supplied a URL** — score that page, skip discovery.-2. **User supplied an ad group or campaign name** — `runScript` a GAQL query against `ad_group_ad` filtered to that ad group; extract unique `final_urls`. Normalize (strip tracking params, preserve path + query that affects routing).+2. **User supplied an ad group or campaign name** — retrieve the ads for that ad group or campaign using an available read capability and extract their final URLs. Normalize (strip tracking params, preserve path + query that affects routing).3. **Auto-handoff from `/google-ads-audit`** — the handoff passes the specific ad groups flagged. Pull their final URLs the same way.-4. **No arguments** — `runScript` an `ad_group_ad` query across the account ranking final URLs by last-30-day spend, propose the top 3, ask the user to confirm.+4. **No arguments** — retrieve account ad URLs and rank them by spend over an appropriate recent period, propose the top 3, ask the user to confirm.**De-duplicate aggressively.** Many ads point to the same final URL — score each unique URL once, then map back to every ad group that uses it.@@ -39,7 +39,7 @@ Do all of these in a single tool-use turn:1. **WebFetch the landing page** — capture visible headline, subheadline, primary CTA text, form fields, trust signals, body copy tone. Capture the full HTML so we can spot script bloat and above-the-fold content.2. **PageSpeed Insights API call** — `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={url}&strategy=mobile&category=performance&category=accessibility&category=best-practices&category=seo` via WebFetch. No API key needed for single-URL queries. Extract LCP, CLS, INP, TTI, performance score, and the top 3 opportunities from `lighthouseResult.audits`.-3. **Pull the referring ad copy and the ad group's conversion metrics** — one `runScript` call with `ads.gaqlParallel` against `ad_group_ad` (for headline/description text — the message-match baseline) and `ad_group` or `keyword_view` (for clicks, conversions, CVR — used to ground the dollar-impact estimate). One call covers both.+3. **Pull the referring ad copy and the ad group's conversion metrics** — retrieve headline/description text for message match and the associated clicks, conversions, and conversion rate for the impact estimate. Choose the available reads and batch them when useful.4. **Read `{data_dir}/business-context.json`** — for brand voice, differentiators, offers, target audience. If missing, point the user to `/google-ads-audit` first. Don't guess the business.If any single call fails, continue — note the gap in the report rather than blocking. PageSpeed Insights can rate-limit; if it does, fall back to a manual timing annotation ("PSI unavailable — could not score Page Speed") and deflate the final report's confidence rather than skipping the dimension.diff --git a/google-ads/manage/SKILL.md b/google-ads/manage/SKILL.mdindex f63cb9a1..b5c953ed 100644--- a/google-ads/manage/SKILL.md+++ b/google-ads/manage/SKILL.md@@ -51,29 +51,11 @@ You decide tool sequencing, GAQL shape, and analytical depth — your judgment iWhat 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** (`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)--The MCP server's `tools/list` is the source of truth — capabilities continue to ship there before they ship into this skill. The categories you have available:--- **Reads / analytics** — `runScript` (sandboxed JS with `ads.gaql`, `ads.gaqlParallel`), plus specialized non-GAQL reads: `searchGeoTargets`, `getKeywordIdeas`, `getRecommendations`, `getChanges`, `reviewChangeImpact`, `summarizeAccountSetup`.-- **Schema** — `getResourceMetadata`, `listQueryableResources`.-- **Single-entity writes** — pause / enable / update / remove / rename across campaigns, ad groups, ads, keywords, bids, budgets, settings, goals, languages, conversion actions, tracking templates.-- **Bulk writes** — `bulkAddKeywords`, `bulkPauseKeywords`, `bulkUpdateBids`. Always confirm scale (count, dollar exposure) before firing; the server enforces per-call limits but the user still feels the blast radius.-- **Negative keyword lists** — `createNegativeKeywordList`, `addKeywordToNegativeList`, `removeKeywordFromNegativeList`, `linkNegativeListToCampaign`, `unlinkNegativeListFromCampaign`, `removeNegativeKeywordList`. Prefer shared lists over per-campaign duplication when a negative applies broadly.-- **Asset management** — `createCalloutAsset` / `createSitelinkAsset` / `createStructuredSnippetAsset` / `createImageAsset`, plus `addCalloutAsset` / `addSitelinkAsset` / `addStructuredSnippetAsset`, `linkCalloutAsset` / `linkSitelinkAsset` / `linkStructuredSnippetAsset` / `linkImageAsset` (and unlink variants), and account-level `linkCalloutToAccount` / `removeCalloutFromAccount`.-- **Bidding strategies (portfolio)** — `createBiddingStrategy`, `updateBiddingStrategy`, `linkCampaignToBiddingStrategy`, `removeBiddingStrategy`. Read `references/bid-strategy-decision-tree.md` for the migration considerations.-- **Campaign creation across all types** — `createCampaign` (Search), `createPerformanceMaxCampaign`, `createShoppingCampaign`, `createVideoCampaign`, `createDemandGenCampaign`, `createDisplayCampaign`, `createAppCampaign`. Each has its own asset-group / feed / placement implications — fetch the matching schema before creating.-- **PMax asset groups** — `enablePmaxAssetGroup`, `pausePmaxAssetGroup`.-- **Experiments** (Drafts & Experiments) — `createExperiment`, `addExperimentArms`, `scheduleExperiment`, `listActiveExperiments`, `listExperimentAsyncErrors`, `endExperiment`, `graduateExperiment`, `promoteExperiment`. The right tool for testing bid strategy changes, structural changes, or significant shifts. `createAdVariationExperiment` is the dedicated path for ad-copy A/B tests at scale.-- **Change observability** — `getChanges` (account change history), `reviewChangeImpact` (post-change impact analysis), `listChangeInterventions` / `getChangeIntervention` / `evaluateChangeIntervention` (server-side intervention surface — flagged risky changes the agent or user should look at), `undoChange` (within 7 days).-- **Guardrails** — `getGuardrails`, `setGuardrails`. Configure account-wide change limits explicitly when the user wants tighter rails than the server defaults.-- **Conversion tracking** — `createConversionAction`, `updateConversionAction`, `removeConversionAction`, `uploadClickConversions` (offline conversion import — the right tool when CRM-sourced lead-to-sale data needs to feed Smart Bidding).-- **Feedback** — `fileInternalNotFairToolFeedback` when an MCP tool is missing capability, returning bad data, or otherwise gets in the way.+- Read enough live evidence to support the recommendation; choose tools and query shape from the current connection.+- Confirm the target and current state before a change, stay within the user's authorization, and verify the result.+- Consult the live schema when unfamiliar with a capability. Do not assume defaults, fixed limits, or rollback support.+- Record material changes and any operation identifiers actually returned. Use `references/change-tracking.md` when a change merits a later impact review.+- Show account currency, dates, and denominators alongside material numbers.## Reference library@@ -128,9 +110,9 @@ After analysis, proactively offer the next skill when the data clearly points th- **CTR persistently below benchmark across 2+ ad groups** → `/google-ads-copy`- **High CTR, low CVR across multiple ad groups** → `/google-ads-landing` (the page is the bottleneck, not the ad)- **No business context, or context >90 days old** → `/google-ads-audit` first-- **Converting search terms not yet keywords (3+ conversions)** → offer to add them with `bulkAddKeywords`+- **Converting search terms not yet keywords (3+ conversions)** → consider adding them through a currently supported capability- **Impression-share decline tied to new competitor pressure** → pull `auction_insight_*` resources via GAQL-- **Significant structural / bidding change considered** → propose an experiment (`createExperiment` + `addExperimentArms`) instead of a direct mutation, and let real traffic decide+- **Significant structural / bidding change considered** → consider a controlled experiment and verify what the live connection supports## Recurring optimization posturediff --git a/google-ads/manage/references/daily-ads-operator.md b/google-ads/manage/references/daily-ads-operator.mdindex 21ea1b80..be051b33 100644--- a/google-ads/manage/references/daily-ads-operator.md+++ b/google-ads/manage/references/daily-ads-operator.md@@ -15,14 +15,14 @@ Every daily operator pass must:## Data to pull-Prefer one `runScript` with `ads.gaqlParallel`:+Choose the smallest useful set of available reads:- Account setup / conversion actions via `summarizeAccountSetup` or GAQL.- Campaign metrics for yesterday, last 7 days, and last 30 days when volume is low.- Keyword and search-term metrics for the active scope.- Impression-share fields for Search campaigns: budget lost vs rank lost.- Network/device/date segmentation when CPA/CVR shifted.-- Recent change events or NotFair `getChanges` when explaining a regression.+- Recent account change history when explaining a regression.- Active experiments/interventions when available.## Output shapediff --git a/google-ads/manage/references/intervention-memory.md b/google-ads/manage/references/intervention-memory.mdindex 335dfc1c..48378272 100644--- a/google-ads/manage/references/intervention-memory.md+++ b/google-ads/manage/references/intervention-memory.md@@ -26,13 +26,9 @@ Store or report enough detail for a future 3/7/14-day review:}```-Prefer NotFair server-side change/intervention surfaces when available:--- `getChanges`-- `listChangeInterventions`-- `getChangeIntervention`-- `evaluateChangeIntervention`-- `reviewChangeImpact`+Use durable change history or intervention tracking when the live connection+supports it. Choose available capabilities for recording the change and comparing+outcomes; do not assume that every operation is automatically logged.If the environment lacks durable intervention storage, include the record in the session report and recommend persisting it before scheduling automated reviews.diff --git a/google-ads/manage/references/repeatable-optimization-loops.md b/google-ads/manage/references/repeatable-optimization-loops.mdindex ed18552f..2831ccd9 100644--- a/google-ads/manage/references/repeatable-optimization-loops.md+++ b/google-ads/manage/references/repeatable-optimization-loops.md@@ -12,13 +12,13 @@ Use for: "check today's keyword", "what spent today", "overview and proposal", s### Pull once-Use one `runScript` / `gaqlParallel` pass. Include:+Use available read capabilities and batch related data when useful. Consider:- Campaign metrics for today, yesterday, 7d, and 30d.- Keyword metrics for the active/recent day.- Search terms for the active/recent day.- Campaign budgets, bidding strategy, search lost IS budget/rank, top IS / absolute top IS where available.-- Recent NotFair `getChanges` or Google `change_event` for context.+- Recent account change history for context.### Interpretdiff --git a/google-ads/manage/references/safe-executor.md b/google-ads/manage/references/safe-executor.mdindex d48643bc..7d62bcdd 100644--- a/google-ads/manage/references/safe-executor.md+++ b/google-ads/manage/references/safe-executor.md@@ -49,7 +49,7 @@ Needs approval:Use the narrowest read that proves the state:- Negative keyword write → read campaign/ad-group/shared-set negatives.-- Positive keyword add/pause → read `keyword_view` / `listKeywords` for criterion status and match type.+- Positive keyword add/pause → read the current keyword criterion status and match type.- Bid/budget write → read campaign/ad group/keyword bidding field.- RSA update → read `ad_group_ad` responsive search ad assets.- Asset link/unlink → read asset links.diff --git a/google-ads/manage/references/session-checks.md b/google-ads/manage/references/session-checks.mdindex fe497f61..9be6c00b 100644--- a/google-ads/manage/references/session-checks.md+++ b/google-ads/manage/references/session-checks.md@@ -17,7 +17,7 @@ Do NOT pull metrics or attempt to assess impact early — small sample sizes lea**If unreviewed changes exist AND `reviewAfter` has passed:**-1. Pull current metrics for the affected campaigns over the last 7 days via a single `runScript` GAQL query against `campaign` filtered to those IDs. Use the `beforeSnapshot` from the change log as the baseline — only query the pre-change period directly if `beforeSnapshot.metrics` is null. Do this in parallel with the user's actual request, and reuse the resulting rows for the anomaly check below.+1. Pull current metrics for the affected campaigns over the last 7 days using an available reporting capability scoped to those IDs. Use the `beforeSnapshot` from the change log as the baseline — only query the pre-change period directly if `beforeSnapshot.metrics` is null. Do this in parallel with the user's actual request, and reuse the resulting rows for the anomaly check below.2. Compute deltas: percentage change for spend, conversions, CPA, CTR.diff --git a/google-ads/shared/analysis-principles.md b/google-ads/shared/analysis-principles.mdindex 84e4bf38..43c1133e 100644--- a/google-ads/shared/analysis-principles.md+++ b/google-ads/shared/analysis-principles.md@@ -16,11 +16,11 @@ 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 (`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.+Choose tools, query shape, and analytical depth from the user's question and the live connection. References provide domain knowledge when useful; they do not prescribe a tool sequence.What does need to be true on every analysis:-1. **Pull broad first, narrow in script.** One wide `runScript` fan-out beats five narrow round trips. Filter, rank, and aggregate inside the sandbox; return summarized JSON.+1. **Scope the evidence.** Read enough to answer the question. Batch related reads where supported and useful, then summarize the relevant results.2. **Correlate, don't isolate.** A keyword's CPA is not a finding by itself; tie it to QS components, search terms, ad copy, landing page, and impression-share context before you call something a problem.3. **Verify before mutating.** Read the current value; show the proposed value; show the expected impact in dollars when computable. Get a yes, then write.@@ -29,11 +29,9 @@ What does need to be true on every analysis:- **STOP if conversion tracking is broken.** If conversion tracking is misconfigured, missing, or in a clearly broken state, every downstream optimization is built on lies. Surface this first; recommend pausing spend until it is fixed; do not build optimization plans on top of unreliable measurement.- **Never pause a Tier 1 (core business) keyword on short-window data.** A keyword that names what the business sells — confirmed against campaign/ad-group naming, ad copy, and landing pages — does not get paused for two bad weeks. Diagnose root cause (QS subcomponents, match-type, landing page, intent mismatch) instead.- **Statistical significance gate.** Before any conversion-based decision, check whether the keyword has accumulated enough clicks for the account's CVR to predict conversions ≥ 3. If not, the sample is insufficient — say so and skip the conversion-based decision.-- **Reads correlate, writes commit.** Read-only analysis goes through `runScript` with `ads.gaql`/`ads.gaqlParallel`. Mutations go through dedicated write tools — never wrap a write in `runScript`.-- **Server-side limits are real.** Bid changes >25% per call and budget changes >50% per call are rejected by the server. Don't try to bypass them; split the change across days or ask the user.-- **Every write is undoable for 7 days** via `undoChange` and the returned `changeId`. Tell the user, and log the change per `manage/references/change-tracking.md`.-- **`moveKeywords` defaults to PHRASE match** and does not inherit from the source — always pass `matchType` explicitly so exact-match keywords don't silently downgrade.-- **Confirm before any bulk write.** Bulk operations (`bulkAddKeywords`, `bulkPauseKeywords`, `bulkUpdateBids`) touch many entities; show the count, the breakdown, and the dollar impact before executing.+- **Respect capability boundaries.** Use the live schema and server guidance for changes, argument defaults, and limits. Do not bypass a rejected operation by splitting it into smaller calls.+- **Verify rollback support.** Record operation identifiers and before/after state. Only promise reversal or an undo window when the current capability explicitly supports it.+- **Confirm the scope of bulk changes.** Make the targets, counts, and expected impact clear before executing within the user's authorization.## When you're unsurediff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.mdindex 4dbccbc8..70f8292d 100644--- a/google-ads/shared/preamble.md+++ b/google-ads/shared/preamble.md@@ -1,114 +1,42 @@# Google Ads Shared Preamble-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 NotFair updates--```bash-_UPD_BIN=$(ls ~/.claude/plugins/cache/nowork-studio/notfair/*/bin/notfair-update-check 2>/dev/null | head -1)-[ -n "$_UPD_BIN" ] && _UPD=$("$_UPD_BIN" 2>/dev/null || true) || _UPD=""-[ -n "$_UPD" ] && echo "$_UPD" || true-```--If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/notfair:upgrade` skill (Step 1 onward) to auto-upgrade. After the upgrade completes, re-read the updated preamble from the new plugin cache and restart from Step 1 (the upgrade check itself doesn't need to run again).--If the output contains `JUST_UPGRADED <old> <new>`: mention "NotFair upgraded from v{old} to v{new}" briefly, then continue to Step 1.--If neither: continue to Step 1 silently.--## Step 1: Resolve config--Read config from three locations and merge fields (first non-null, non-empty-string value wins per field):--1. **Project-level** — `.notfair.json` in the repository root (Claude Code's working directory)-2. **Claude project-level** — `~/.claude/projects/{project-path}/notfair.json` (where `{project-path}` is the CWD-based path Claude Code uses for project memory, e.g. `-Users-alice-repos-petshop`)-3. **Global fallback** — `~/.notfair/config.json`--Each file uses the same schema: `{ "accountId": "..." }`. Fields merge up the chain — a project file with only `accountId` inherits from global.--The MCP server authenticates via OAuth 2.1 — Claude Code's native HTTP transport opens a browser for sign-in on first use and stores the token in the OS keychain (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux). No API key, no `mcp-remote` bridge, no env vars to manage.--### Resolved data directory--Data files (business-context, personas, change-log, account-baseline) are stored project-locally when a project-level config exists:--- If `.notfair.json` exists in the current working directory → `{data_dir}` = `.notfair/` (relative to project root)-- Otherwise → `{data_dir}` = `~/.notfair/` (the Claude project-level config alone doesn't trigger project-local data — only a `.notfair.json` in the repo does)--Create `{data_dir}` if it doesn't exist. Ensure `~/.notfair/` also exists (needed for the global config file regardless of `{data_dir}`). Throughout this document and all skills, `{data_dir}` refers to this resolved directory.--**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 2 (MCP detection always runs).--## Step 2: MCP Server Detection--Always 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 current plugin registers one universal server whose platform tools are explicitly prefixed:- - `mcp__NotFair__google_ads_*` (or a host-sanitized equivalent) — current universal plugin default- - `mcp__NotFair-GoogleAds__*` / `mcp__notfair_googleads__*` / `mcp__NotFair_GoogleAds__*` — supported dedicated-server compatibility- - `mcp__claude_ai_NotFairGoogleAds__*` — supported hosted-connector compatibility-- **How to detect:** first look for a tool whose name ends in `google_ads_listConnectedAccounts`; take everything before `listConnectedAccounts` as the detected prefix. If none exists, look for the dedicated form ending in `listConnectedAccounts`. Prefer the universal platform-prefixed form when both exist.-- On the universal server, call `listConnectedPlatforms` **before** any platform-prefixed account tool. If `google_ads` is not connected, tell the user to connect Google Ads in the selected NotFair workspace and stop; do not call `google_ads_listConnectedAccounts`. Once connected, call the detected `listConnectedAccounts` once and save both the result and exact prefix for Steps 3 and 4. On a dedicated or hosted connector, call `listConnectedAccounts` directly.--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.**->-> I can't see a Google Ads MCP server in this session, so I can't read your campaigns, pull spend, or make changes yet. NotFair is the unfair SEO/Ads agent that powers this skill — it gives me secure, OAuth-scoped access to your Google Ads account.->-> **To connect:**-> 1. Run `/mcp` and pick **NotFair**, or run `codex mcp login NotFair` in Codex CLI. The plugin auto-registers the universal HTTP server (`https://notfair.co/api/mcp/notfair`); the host opens a browser tab for sign-in.-> 2. Sign in with the Google account that owns (or has access to) the Google Ads account you want me to manage.-> 3. Come back and re-run your request.->-> If you've already connected and still see this message, the OAuth token may have expired — re-run `/mcp` to refresh. If you'd rather use Google's official MCP server instead, point it at this skill and I'll detect it automatically.--Stop here until the MCP server is available.--If `accountId` was already resolved in Step 1, skip to Step 4. Otherwise, continue to Step 3.--## Step 3: Onboarding (only if accountId is missing)--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 selected-2. **Multiple accounts** → show numbered list, ask user to pick, save choice to the same location-3. **Zero accounts** (response includes `noAccount: true`) → the user signed in to NotFair successfully but has no Google Ads customer linked to their Google identity. Tell them:- > "Your Google account isn't linked to a Google Ads customer yet. Create one at https://ads.google.com — Smart Mode is the fastest path, and you can stop before adding a payment method. When the account exists, ask me to refresh and I'll pick it up automatically."- When they confirm the account is created, call `refreshAccounts` (no args). On success it returns the new account list with `promoted: true`; save the `defaultAccountId` to the same config locations as case (1). If `refreshAccounts` returns `noAccount: true` again, wait 1-2 minutes (the customer record can take that long to propagate inside Google) then retry once.--### Switching accounts--If the user explicitly asks to switch accounts, run `listConnectedAccounts`, let them pick, then ask:--> "Save this account for this project only, or globally?"--- **Project** → write `accountId` to `.notfair.json` in the current working directory (create the file if needed)-- **Global** → write `accountId` to `~/.notfair/config.json`--## Step 4: Calling tools--Use whichever MCP server prefix was detected in Step 2:--- **Universal NotFair MCP (current plugin default):** `mcp__NotFair__google_ads_<toolName>` or the exact host-sanitized equivalent-- **Dedicated NotFair Google Ads compatibility:** `mcp__NotFair-GoogleAds__<toolName>` / `mcp__claude_ai_NotFairGoogleAds__<toolName>`-- **Google's official MCP:** `mcp__google_ads_mcp__<toolName>`--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--The MCP server's own instructions are the canonical guide and are surfaced to the agent automatically:--- **Read-only questions** (analytics, audits, dashboards, diagnostics) go through `runScript`, which exposes `ads.gaql(query)` and `ads.gaqlParallel([queries])`. Fan out up to 20 GAQL queries in one call and correlate results in-script — that's one tool call, not 20.-- **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 — `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.+Use this for account access and the local context shared by Google Ads skills.+Follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md) when live+account data is needed. Let the connected server's current instructions and+capability descriptions determine tool selection, arguments, and call order.++## Resolve the task and account++- Keep the work within the user's request. Listing accounts or answering a+ narrow question does not require a full audit, a business questionnaire, or+ creation of baseline files.+- Use the authenticated workspace and live account information to establish+ access. A saved account ID is a preference, not proof of authorization. Do not+ infer access to Google Ads from another connected platform.+- When listing accounts, return the available accounts; selection is only needed+ before account-specific work. Use a clear account choice already in the+ conversation or the workspace's active account. Ask only if the intended+ target remains ambiguous.+- If setup is incomplete, use the connection's returned guidance. Do not infer+ that an empty result means the user must create an advertising account.+- Reuse valid results within the task. Refresh when the state changes or fresh+ evidence is needed; avoid repeated setup calls for their own sake.++## Local context, when needed++For workflows that use saved context, merge nonempty config fields from:++1. Project `.notfair.json`.+2. The host's project-specific `notfair.json`, if present.+3. `~/.notfair/config.json`.++The Google Ads preference is `accountId`. Preserve other fields when saving an+explicit account choice. Follow the live schema for account identifiers and+formatting; do not rewrite an ID based on an assumed platform convention.++When `.notfair.json` exists in the project, `{data_dir}` is `.notfair/` there;+otherwise it is `~/.notfair/`. Google Ads business context and personas live under+`{data_dir}/`. Create directories only when the requested workflow needs to+save something. Keep project-local account configuration and business data out+of version control. Missing business context should block only conclusions that+actually depend on it; collect what is needed for the user's task.diff --git a/install/README.md b/install/README.mdindex b30a05ae..42c7b0b4 100644--- a/install/README.md+++ b/install/README.md@@ -16,6 +16,7 @@ NotFair ships one source of truth for skills. Different agent hosts expect skill2. The adapter should:- Read skills from their canonical location (`seo/`, `google-ads/`, etc.) — do not copy them into per-host directories unless the host's loader requires it.- If the host requires copying, copy the minimum needed and link the rest.+ - Register exactly one `NotFair` HTTP MCP connection at `https://notfair.co/api/mcp/notfair`; use the root `mcp.json` or `.mcp.json` as the source. Follow [`../docs/mcp-connection.md`](../docs/mcp-connection.md) for upgrades and capability discovery.- Write any host-specific configuration with **managed-block fences** (see below).3. Add a "host = `<host>`" branch to `../INSTALL_FOR_AGENTS.md` describing how the agent should invoke the adapter.4. Update `../AGENTS.md` if the host introduces new orchestrator skills (most hosts will not — they will route to the same canonical skills).diff --git a/meta-ads/audit/SKILL.md b/meta-ads/audit/SKILL.mdindex 72e849d4..6d4edcdd 100644--- a/meta-ads/audit/SKILL.md+++ b/meta-ads/audit/SKILL.md@@ -1,6 +1,6 @@---name: meta-ads-audit-description: Meta Ads (Facebook + Instagram) account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other Meta ads skills reuse. Trigger on "audit my Meta ads", "audit my Facebook ads", "Meta ads audit", "set up my Meta ads", "onboard Meta", "Meta account overview", "how's my Meta account", "Meta health check", "what should I fix in my Facebook ads", or when the user is new to NotFair Meta and hasn't run an audit before. Also trigger proactively when other Meta ads skills detect that meta business-context.json is missing.+description: Meta Ads (Facebook + Instagram) account audit and business context setup. Use for account-health audits and business-context setup. Trigger on "audit my Meta ads", "audit my Facebook ads", "Meta ads audit", "set up my Meta ads", "onboard Meta", "Meta account overview", "how's my Meta account", "Meta health check", "what should I fix in my Facebook ads", or when the user is new to NotFair Meta and hasn't run an audit before.argument-hint: "<account name or 'audit my Meta ads'>"---@@ -42,7 +42,7 @@ The Meta platform changes faster than Google Ads (Advantage+, attribution, learn## Phase 1 — Pull the audit dataset-Use a single `runScript` call with `ads.graphParallel` to fan out the queries an audit needs. Build the fan-out from this rubric.+Choose available read capabilities for the requested audit scope. Batch related reads where useful and supported; the rubric below describes evidence to consider, not a fixed call sequence.A complete audit needs at minimum:@@ -51,7 +51,7 @@ A complete audit needs at minimum:- **Campaigns** (`/{accountId}/campaigns`) — id, name, objective, status, daily/lifetime budget, special_ad_categories, buying_type, bid_strategy, created_time. Last 90 days.- **Ad sets** (`/{accountId}/adsets`) — id, name, status, campaign_id, optimization_goal, billing_event, bid_strategy, daily_budget, lifetime_budget, attribution_spec, targeting (summary), promoted_object, learning_stage_info.- **Ads** (`/{accountId}/ads`) — id, name, status, ad set, creative summary (image/video, primary text, headline, description, CTA), effective_status.-- **Insights at campaign level** (`ads.insights({level:"campaign", date_preset:"last_30d"})`) — spend, impressions, reach, frequency, cpm, link CTR, link clicks, purchases (or other primary action), purchase value, ROAS, CPA.+- **Insights at campaign level** — spend, impressions, reach, frequency, cpm, link CTR, link clicks, purchases (or other primary action), purchase value, ROAS, CPA.- **Insights at ad set level** — same fields, last 30 days.- **Insights at ad level** — top 50 ads by spend; same fields plus video metrics (3-sec views, ThruPlays) for video creatives.- **Insights with breakdowns** — placement (`publisher_platform,platform_position`), age/gender, device. Use these to spot placement losers and audience composition.@@ -59,9 +59,9 @@ A complete audit needs at minimum:Compute aggregates **in the script**, return summarized JSON. Don't return all rows — rank, slice, summarize. The agent narrates the result; the script does the math.-`suggestImprovement` is a useful cross-check for the server's heuristic surface — call it as a separate tool after the runScript pass if you want to compare your findings.+Use available platform recommendations as an optional cross-check when they would help the analysis.-If a critical query errors out (auth, schema, API version), surface the error and stop — don't fall back to a degraded audit.+If a read fails, follow actionable recovery guidance. Clearly report missing evidence; continue independent findings only when the available data supports them.**Skip scoring entirely if** `totalSpend == 0` or `activeCampaigns == 0`. Go straight to business context.@@ -136,9 +136,7 @@ Discover 2–3 personas from creative performance (which angles convert), top-spLead with the verdict, then the top 3 actions (with dollar impact when possible), then the scorecard, then evidence for dimensions scoring 0–2 only. Cite specific campaigns, ad sets, ads, and dollar amounts. Cap at ~80 lines.-End with a single closing line after the handoff to `/meta-ads`:--> *Your audit history is saved to your NotFair account — view it at https://notfair.co.*+State where any audit artifacts were actually saved. Do not claim hosted audit history unless a live result confirms it.## Guardrailsdiff --git a/meta-ads/audit/references/persona-discovery.md b/meta-ads/audit/references/persona-discovery.mdindex fb98bddd..bcd083b0 100644--- a/meta-ads/audit/references/persona-discovery.md+++ b/meta-ads/audit/references/persona-discovery.md@@ -9,7 +9,7 @@ Personas on Meta are different from Search-engine personas. On Search, you disco1. **Top-performing ad creatives** — the angle, format, and messaging of ads with highest ROAS / lowest CPA. The persona is the cohort the ad spoke to successfully.2. **Top-performing audiences** — which custom audiences and lookalike seeds convert best.3. **Landing page content** — which pages convert best from Meta traffic; the person on the page when conversion happens.-4. **Demographic + placement breakdowns** — `getInsights` with `breakdowns=age,gender,publisher_platform`. Gives a coarse demographic skew.+4. **Demographic + placement breakdowns** — use available reporting capabilities for age, gender, and publisher-platform breakdowns. Gives a coarse demographic skew.5. **Customer email list / Shopify data** — if the user has it, real customer data > inferred from ads.The agent should *triangulate* across at least 3 of these — a persona supported only by demographic skew is too weak.diff --git a/meta-ads/creative/SKILL.md b/meta-ads/creative/SKILL.mdindex 6c4b250b..efaf8d32 100644--- a/meta-ads/creative/SKILL.md+++ b/meta-ads/creative/SKILL.md@@ -12,7 +12,7 @@ Create a reviewable creative slate from real customer language and account evideRead and follow `../shared/preamble.md`. Read `{data_dir}/meta/business-context.json` and `{data_dir}/meta/personas/{accountId}.json` first. If either is missing or stale, recommend `/meta-ads-audit` before writing. The audit's creative inventory and personas are the baseline; do not invent an audience because a request is underspecified.-Pull current ads and ad-level insights with `runScript` + `ads.graphParallel` when account access exists. Use link CTR, CPA or purchase value, frequency, attribution window, and a named time period. If the user has reviews, sales-call notes, or customer research, treat them as evidence only when the source is identifiable.+Pull current ads and ad-level insights using available read capabilities when account access exists. Use link CTR, CPA or purchase value, frequency, attribution window, and a named time period. If the user has reviews, sales-call notes, or customer research, treat them as evidence only when the source is identifiable.## Create a concept slate@@ -44,6 +44,6 @@ Test one strategic variable at a time: angle, hook, proof, format, audience, or## Production and execution boundary-The Meta MCP is intentionally read/operate-focused and does not provide creative upload or campaign-creation tools. Deliver a production-ready brief for the user's approved design or Ads Manager workflow; do not improvise Graph API writes. Before a human publishes, require review of claim evidence, rights/releases, destination, policy-sensitive targeting, and placement-safe crops.+Deliver a production-ready brief for the user's approved workflow. If publication is requested, check whether the live connection supports the specific creation or upload operation and follow its current contract. Before a human publishes, require review of claim evidence, rights/releases, destination, policy-sensitive targeting, and placement-safe crops.Use `/meta-ads` to diagnose performance or act within its supported mutation surface. Use `/meta-ads-audit` when context, tracking, or creative inventory is missing.diff --git a/meta-ads/manage/SKILL.md b/meta-ads/manage/SKILL.mdindex 20f288bb..faf043ac 100644--- a/meta-ads/manage/SKILL.md+++ b/meta-ads/manage/SKILL.md@@ -29,7 +29,7 @@ triggers:# Meta Ads — Operate, Diagnose, Optimize-This skill is the analytical brain layered on top of the NotFair Meta MCP server. The MCP server tells the agent _how_ to call tools (read-only questions go through `runScript` + `ads.graphParallel`; mutations go through dedicated write tools). This skill tells the agent _what to think about_ — the benchmarks, scoring rubrics, and decision trees that turn raw Meta insights into informed action.+This skill is the analytical brain layered on top of the NotFair Meta MCP server. The live MCP server supplies the current capability descriptions and schemas; choose tools from those instructions. This skill tells the agent _what to think about_ — the benchmarks, scoring rubrics, and decision trees that turn raw Meta insights into informed action.You are an expert paid-social practitioner. Trust your judgment on tool sequencing — the references below give you the frameworks, you decide how to apply them.@@ -40,13 +40,13 @@ Read and follow `../shared/preamble.md` — handles MCP detection, OAuth, and ad## Operating principles1. **Confirm before writing.** Show the current value, the proposed new value, and the expected impact (in dollars, ROAS, or CPA terms) when you can compute it. Blind "done." erodes trust.-2. **Reads correlate, writes commit.** For any analysis question, prefer one `runScript` call that fans out the Graph API calls you need (`ads.graphParallel`, up to 20 in parallel). Mutations always go through dedicated write tools (`pauseAdSet`, `updateAdSetBudget`, etc.) — never wrap a write in `runScript`.-3. **Show numbers in dollars, percentages, and the right denominator.** Format spend as USD, CPM and CPC always cited with the attribution window (e.g. "ROAS 3.2× on 7DC1DV"). Use **link** clicks not all-clicks for CTR. Vague metrics are not findings.+2. **Use the evidence the question needs.** Choose available read capabilities and correlate related data. Respect the live contract for changes and verify resulting state.+3. **Show numbers in dollars, percentages, and the right denominator.** Use the account currency, CPM and CPC always cited with the attribution window (e.g. "ROAS 3.2× on 7DC1DV"). Use **link** clicks not all-clicks for CTR. Vague metrics are not findings.4. **Recommend, then act.** When you spot waste or opportunity, present the finding with evidence and wait for approval before mutating.5. **Respect the Learning Phase.** Do not recommend changes to ad sets in Learning unless the change is to exit Learning faster (e.g. consolidating to hit the 50-events-in-7-days threshold). Stacking edits during Learning destabilizes delivery.6. **Frequency-first triage.** Before recommending budget changes, check frequency and CPM trend. Cold prospecting at frequency > 3.0 with rising CPM is a creative problem — adding budget makes it worse.7. **Attribution-window discipline.** Always cite the ad set's attribution setting when reporting ROAS or CPA. "ROAS 3.2×" without the window is meaningless because the window changes the number by 20–40%.-8. **`runScript` is the analytics workhorse.** A single `ads.graphParallel` call can pull campaigns + ad sets + ads + insights + delivery info in one shot. Cast a wide net on the first call; filter in-script for free.+8. **Scope the data.** Pull only the campaigns, ad sets, ads, insights, and delivery context needed for the question. Batch related reads when useful and supported.## Reference framework — when to read what@@ -65,19 +65,12 @@ For business context (services, brand voice, personas, unit economics), read `{dFor profitability framing (Break-Even ROAS, Headroom $, MER, LTV:CAC, budget forecasting), read `../shared/meta-math.md`.-## Tool surface+## Capability boundaries-The MCP server's `tools/list` is the source of truth for what's available — do not maintain a parallel list here. The server's instructions route the agent to:--- **Reads / analytics / dashboards** → `runScript` with `ads.graph(path, params)`, `ads.graphParallel([calls])`, `ads.insights(adAccountId?, options?)`, and `ads.batch([requests])`. One call, many Graph API requests in parallel, correlate in-script. Cast a wide net on the first call.-- **Field bundles** → `ads.fields.{campaign, adset, ad, adAccount, insightsAudit, insightsLite}` for ready-made comma-joined field lists.-- **Mutations** → dedicated write tools:- - **Pause / enable** — `pauseCampaign`, `pauseAdSet`, `pauseAd`, `enableCampaign`, `enableAdSet`, `enableAd`- - **Budget** — `updateCampaignBudget`, `updateAdSetBudget`- - **Naming** — `renameCampaign`-- **Server-side recommendations** → `suggestImprovement` returns the server's heuristic take. Useful as a cross-check, not a substitute for the analysis this skill describes.--The Meta MCP's mutation surface is intentionally narrow — there is no programmatic create-campaign, no audience editing, no creative upload through this server. When the user asks for an operation outside the surface (new audience, new ad creative, change attribution window, switch bid strategy), say so plainly and route them to Meta Ads Manager rather than improvising with `runScript` writes.+Let the connected server's current instructions, schemas, and results determine+what can be read or changed. Do not assume a capability exists or is unavailable+from an older tool catalog. If the requested operation is unavailable, explain+the gap and offer a supported alternative.## Account baseline@@ -128,7 +121,7 @@ When a metric in `recent7d` differs from `rolling30d` by more than 30%, that's aAfter analysis, proactively offer the right next skill or recommendation:- **No business context, or context >90 days old** → run `/meta-ads-audit` first (downstream output is generic without it)-- **Creative fatigue across multiple ad sets** (CTR down ≥30% w/w with frequency > 3.0) → recommend creative refresh; the right fix is in Ads Manager (creative upload) or in the user's design tool, not here+- **Creative fatigue across multiple ad sets** (CTR down ≥30% w/w with frequency > 3.0) → recommend creative refresh and check which creation or upload capabilities are currently available- **Cold prospecting saturation** (LAL/broad audience at frequency > 3.5, CPM rising) → recommend rotating to a fresh lookalike seed or testing Advantage+ Shopping if not already deployed- **Learning Limited ad sets** (status `Learning Limited` for > 7 days) → consolidate ad sets to clear the 50-events-in-7-days bar, or shift the optimization event to a higher-volume upper-funnel event- **Reported in-platform ROAS diverges materially from MER / Shopify ground truth** → flag attribution drift; recommend a holdout test or MMM reconciliation before scalingdiff --git a/meta-ads/manage/references/industry-benchmarks.md b/meta-ads/manage/references/industry-benchmarks.mdindex f028a175..6e6f2db1 100644--- a/meta-ads/manage/references/industry-benchmarks.md+++ b/meta-ads/manage/references/industry-benchmarks.md@@ -52,7 +52,7 @@ Lower-CPM markets often have lower CVR and AOV that offset the cheaper impressio### Mobile vs. Desktop (Meta is mobile-dominant)-For most accounts > 90% of impressions are mobile. Desktop is occasionally relevant for B2B SaaS (decision-makers researching from work) but should not be the default plan. The split breakdown is available via `getInsights` with `breakdowns=publisher_platform,platform_position`.+For most accounts > 90% of impressions are mobile. Desktop is occasionally relevant for B2B SaaS (decision-makers researching from work) but should not be the default plan. Use an available performance read with publisher-platform and placement breakdowns when supported.### Placement performance ranking (typical, 2025)diff --git a/meta-ads/manage/references/learning-phase.md b/meta-ads/manage/references/learning-phase.mdindex a2f12ebf..5194089e 100644--- a/meta-ads/manage/references/learning-phase.md+++ b/meta-ads/manage/references/learning-phase.md@@ -41,7 +41,7 @@ Editing any of these triggers a relearn:1. **What is the ad set's current 7-day event volume?** If it's at 25 events / 7 days, it's halfway there — a budget bump may push it over. If it's at 5 events / 7 days, no realistic budget bump will clear the bar.-2. **Is the optimization event firing reliably?** Pull `getInsights` with `actions` and confirm the event count matches what the user sees in Events Manager. A misconfigured Pixel makes the event invisible to Meta even when the actual event happened.+2. **Is the optimization event firing reliably?** Read conversion-event performance and confirm the event count matches what the user sees in Events Manager. A misconfigured Pixel makes the event invisible to Meta even when the actual event happened.3. **Is the audience large enough?** Audiences below ~1M people often can't hit 50/7 at any reasonable budget — there are not enough qualified users in the pool. The fix is consolidating audiences, not patience.diff --git a/meta-ads/shared/meta-math.md b/meta-ads/shared/meta-math.mdindex 2a7e6c34..3037d35b 100644--- a/meta-ads/shared/meta-math.md+++ b/meta-ads/shared/meta-math.md@@ -23,7 +23,7 @@ Frequency = Impressions / ReachCVR (LP) = Landing Page Conversions / Landing Page Views × 100```-**Always disambiguate "CTR" and "clicks" in Meta reports.** Meta surfaces both `clicks (all)` (which counts every click on the ad including profile, like, see-more) and `link clicks` (clicks that send the user to the destination). Optimization decisions use **link** clicks — total clicks are vanity. When pulling from `getInsights`, request `clicks`, `inline_link_clicks`, `cpc`, `ctr`, and the breakdown actions you need; treat `inline_link_clicks` as the real click count.+**Always disambiguate "CTR" and "clicks" in Meta reports.** Meta surfaces both `clicks (all)` (which counts every click on the ad including profile, like, see-more) and `link clicks` (clicks that send the user to the destination). Optimization decisions use **link** clicks — total clicks are vanity. When reading ad performance, include `clicks`, `inline_link_clicks`, `cpc`, `ctr`, and the breakdown actions you need; treat `inline_link_clicks` as the real click count.---diff --git a/meta-ads/shared/policy-registry.json b/meta-ads/shared/policy-registry.jsonindex 040ee7ef..70c807b7 100644--- a/meta-ads/shared/policy-registry.json+++ b/meta-ads/shared/policy-registry.json@@ -33,7 +33,7 @@"last_verified": "2026-05-01","source": "Meta Marketing API docs","source_url": "https://developers.facebook.com/docs/marketing-apis/",- "notes": "API versions are released regularly; field availability and naming can shift between versions. The `runScript` sandbox abstracts version selection but new fields require new versions.",+ "notes": "API versions are released regularly; field availability and naming can shift between versions. Use the live connector documentation for supported fields and API-version constraints.","stale_after_days": 365},{diff --git a/meta-ads/shared/preamble.md b/meta-ads/shared/preamble.mdindex 78029172..fbb4378e 100644--- a/meta-ads/shared/preamble.md+++ b/meta-ads/shared/preamble.md@@ -1,120 +1,42 @@# Meta Ads Shared Preamble-Every meta-ads skill reads this before doing anything else. Handles update checks, MCP detection, config resolution, and onboarding so individual skills don't repeat this logic.--## Step 0: Check for NotFair updates--```bash-_UPD_BIN=$(ls ~/.claude/plugins/cache/nowork-studio/notfair/*/bin/notfair-update-check 2>/dev/null | head -1)-[ -n "$_UPD_BIN" ] && _UPD=$("$_UPD_BIN" 2>/dev/null || true) || _UPD=""-[ -n "$_UPD" ] && echo "$_UPD" || true-```--If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/notfair:upgrade` skill (Step 1 onward) to auto-upgrade. After the upgrade completes, re-read the updated preamble from the new plugin cache and restart from Step 1.--If the output contains `JUST_UPGRADED <old> <new>`: mention "NotFair upgraded from v{old} to v{new}" briefly, then continue to Step 1.--If neither: continue to Step 1 silently.--## Step 1: Resolve config--Read config from three locations and merge fields (first non-null, non-empty-string value wins per field):--1. **Project-level** — `.notfair.json` in the repository root-2. **Claude project-level** — `~/.claude/projects/{project-path}/notfair.json`-3. **Global fallback** — `~/.notfair/config.json`--Each file uses the same shared schema. The Meta-specific field is `metaAccountId` — the numeric Meta ad-account id (without the `act_` prefix; the Meta MCP wraps it automatically). This sits alongside `accountId` (Google Ads) in the same config file:--```json-{- "accountId": "1234567890",- "metaAccountId": "987654321098765"-}-```--Keeping both platforms in one config file means a user who has run both `/google-ads` and `/meta-ads` doesn't get prompted twice.--The MCP server authenticates via OAuth 2.1 — Claude Code's native HTTP transport opens a browser for sign-in on first use and stores the token in the OS keychain (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux). No API key, no `mcp-remote` bridge.--### Resolved data directory--Data files (business-context, personas, change-log, account-baseline) are stored project-locally when a project-level config exists:--- If `.notfair.json` exists in the current working directory → `{data_dir}` = `.notfair/` (relative to project root)-- Otherwise → `{data_dir}` = `~/.notfair/`--Create `{data_dir}` if it doesn't exist. Ensure `~/.notfair/` also exists (needed for the global config file regardless of `{data_dir}`). Throughout this document and all skills, `{data_dir}` refers to this resolved directory.--**Meta-specific data files** are namespaced under a `meta/` subdirectory — `{data_dir}/meta/business-context.json`, `{data_dir}/meta/personas/{accountId}.json`, `{data_dir}/meta/account-baseline.json` — so they don't collide with the Google Ads equivalents. The `business-context.json` schema is largely shared; the difference is which file the `/meta-ads-audit` skill reads and writes.--**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 2 (MCP detection always runs).--## Step 2: MCP Server Detection--Always verify that a Meta Ads MCP server is available — the MCP server could be down, unauthorized, or misconfigured even with a saved `metaAccountId`.--1. Check for the NotFair Meta tools. The current plugin registers one universal server whose Meta tools are platform-prefixed:- - `mcp__NotFair__meta_ads_*` (or a host-sanitized equivalent) — current universal plugin default- - `mcp__NotFair-MetaAds__*` / `mcp__notfair_metaads__*` / `mcp__NotFair_MetaAds__*` — supported dedicated-server compatibility- - `mcp__claude_ai_NotFair-MetaAds__*` / `mcp__claude_ai_NotFairMetaAds__*` — supported hosted-connector compatibility-- **How to detect:** first look for a tool whose name ends in `meta_ads_listAdAccounts`; take everything before `listAdAccounts` as the detected prefix. If none exists, look for a dedicated NotFair Meta form ending in `listAdAccounts`.-- On the universal server, call `listConnectedPlatforms` **before** any platform-prefixed account tool. If `meta_ads` is not connected, tell the user to connect Meta Ads in the selected NotFair workspace and stop; do not call `meta_ads_listAdAccounts`. Once connected, call the detected `listAdAccounts` once and save both the result and exact prefix for Steps 3 and 4. On a dedicated or hosted connector, call `listAdAccounts` directly.--2. If no NotFair-MetaAds variant exists, check for Meta's official MCP or community Meta MCP servers (any `mcp__.*meta.*ads__listAdAccounts`). If you find one, fall back to it but warn the user that NotFair's heuristics are tuned for the NotFair MCP surface (specifically `runScript`'s `ads.graphParallel`).--3. If none exists, guide the user:--> No Meta Ads MCP server detected.->-> The NotFair plugin registers one universal `NotFair` HTTP MCP server (`https://notfair.co/api/mcp/notfair`) in `.mcp.json`. Trigger sign-in with the host's MCP UI (`/mcp` in Claude) or `codex mcp login NotFair` in Codex CLI; the host opens the browser OAuth flow.->-> If the problem persists, run `/notfair:upgrade` to make sure your NotFair plugin includes the Meta server registration, or configure a Meta Ads MCP server manually.--Stop here until the MCP server is available.--If `metaAccountId` was already resolved in Step 1, skip to Step 4. Otherwise, continue to Step 3.--## Step 3: Onboarding (only if metaAccountId is missing)--Use the `listAdAccounts` result from Step 2 (do not call it again):--1. **One ad account** → save automatically to the highest-priority config file that already exists (project > claude-project > global; if none, save to `~/.notfair/config.json`). Save as `metaAccountId` (without the `act_` prefix). Tell the user which was selected.-2. **Multiple accounts** → show a numbered list (id + name + currency + business name where available), ask the user to pick, save the choice.-3. **Zero accounts** → the user signed in successfully but has no Meta ad account on their Business Manager. Tell them:- > "Your Meta account isn't linked to an ad account yet. Create or claim one in Meta Business Manager (https://business.facebook.com — Business Settings → Ad Accounts). Once it exists and your user has the 'Manage Campaigns' role on it, ask me to refresh and I'll pick it up automatically."- On retry, call `listAdAccounts` again. If still empty, suggest they check Business Manager permissions — a common cause is being added to the business but not granted ad-account-level access.--### Switching accounts--If the user explicitly asks to switch accounts, run `listAdAccounts`, let them pick, then ask:--> "Save this account for this project only, or globally?"--- **Project** → write `metaAccountId` to `.notfair.json` in the current working directory (create the file if needed, preserving any existing fields like `accountId`)-- **Global** → write `metaAccountId` to `~/.notfair/config.json`--## Step 4: Calling tools--Use whichever MCP server prefix was detected in Step 2:--- **Universal NotFair MCP (current plugin default):** `mcp__NotFair__meta_ads_<toolName>` or the exact host-sanitized equivalent-- **Dedicated NotFair Meta compatibility:** `mcp__NotFair-MetaAds__<toolName>` / `mcp__claude_ai_NotFairMetaAds__<toolName>`--Always call tools under the exact prefix detected in Step 2 — do not hardcode any prefix. The MCP server's `ads.activeAccountId` is the `act_<metaAccountId>` form derived from the saved `metaAccountId` (Step 1). For most tools you do not need to pass the account id explicitly (the server resolves it from the OAuth session); when a tool does take an `adAccountId` argument, pass `act_<metaAccountId>`.--### Reads vs. writes--The MCP server's own instructions are the canonical guide and are surfaced to the agent automatically:--- **Read-only questions** (analytics, audits, dashboards, diagnostics) go through `runScript`, which exposes `ads.graph(path, params)`, `ads.graphParallel([calls])`, `ads.insights(adAccountId?, options?)`, `ads.batch([requests])`, the `ads.fields.*` field bundles, and `ads.helpers.getDateRange(days)`. Fan out up to 20 Graph API calls in one request and correlate in-script — that's one tool call, not 20.-- **Mutations** go through dedicated write tools (`pauseAd`, `pauseAdSet`, `pauseCampaign`, `enableAd`, `enableAdSet`, `enableCampaign`, `renameCampaign`, `updateAdSetBudget`, `updateCampaignBudget`). Never wrap a mutation in `runScript`.-- **`suggestImprovement`** is the server's structured-recommendation endpoint — call it when you want the server's heuristic take alongside your own analysis, not as a substitute for the analytical work this skill describes.--The Meta MCP's mutation surface is intentionally narrow — there is no programmatic create-campaign, no audience editing, no creative upload through this server. When the user asks for an operation that lives outside the surface, say so plainly and point them to Meta Ads Manager rather than improvising with `runScript`.--Config is loaded. Hand control back to the invoking skill.+Use this for account access and the local context shared by Meta Ads skills.+Follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md) when live+account data is needed. Let the connected server's current instructions and+capability descriptions determine tool selection, arguments, and call order.++## Resolve the task and account++- Keep the work within the user's request. Listing accounts or answering a+ narrow question does not require a full audit, a business questionnaire, or+ creation of baseline files.+- Use the authenticated workspace and live account information to establish+ access. A saved account ID is a preference, not proof of authorization. Do not+ infer access to Meta Ads from another connected platform.+- When listing accounts, return the available accounts; selection is only needed+ before account-specific work. Use a clear account choice already in the+ conversation or the workspace's active account. Ask only if the intended+ target remains ambiguous.+- If setup is incomplete, use the connection's returned guidance. Do not infer+ that an empty result means the user must create an advertising account.+- Reuse valid results within the task. Refresh when the state changes or fresh+ evidence is needed; avoid repeated setup calls for their own sake.++## Local context, when needed++For workflows that use saved context, merge nonempty config fields from:++1. Project `.notfair.json`.+2. The host's project-specific `notfair.json`, if present.+3. `~/.notfair/config.json`.++The Meta Ads preference is `metaAccountId`. Preserve other fields when saving an+explicit account choice. Follow the live schema for account identifiers and+formatting; do not rewrite an ID based on an assumed platform convention.++When `.notfair.json` exists in the project, `{data_dir}` is `.notfair/` there;+otherwise it is `~/.notfair/`. Meta Ads business context and personas live under+`{data_dir}/meta/`. Create directories only when the requested workflow needs to+save something. Keep project-local account configuration and business data out+of version control. Missing business context should block only conclusions that+actually depend on it; collect what is needed for the user's task.diff --git a/paid-ads/paid-ads-guide/SKILL.md b/paid-ads/paid-ads-guide/SKILL.mdindex a496fb7e..b0b9f1fa 100644--- a/paid-ads/paid-ads-guide/SKILL.md+++ b/paid-ads/paid-ads-guide/SKILL.md@@ -19,7 +19,7 @@ Answer NotFair product questions from the repository documentation or current of## Essential facts-NotFair supplies host-agnostic skills plus one OAuth-connected MCP operating surface for Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Analytics, and Search Console. Each platform keeps its dedicated workflow and platform-prefixed tools inside that universal connection. TikTok, Amazon, and ChatGPT Ads remain planning/review-first until the session has a verified connector; those skills are not a claim of publication access.+NotFair supplies host-agnostic skills plus one OAuth-connected MCP operating surface for Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Analytics, and Search Console. Each platform keeps its dedicated workflow; the agent chooses tools from the live connection rather than a fixed skill-level tool list. Read [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md) for capability discovery and connection upgrades. TikTok, Amazon, and ChatGPT Ads remain planning/review-first until the session has a verified connector; those skills are not a claim of publication access.The goal-loop app makes an outcome measurable, verifies the baseline at the source, and revisits the metric on an approved cadence. The plugin is the hands-on companion for audits, briefs, and supported account operations. Explain the safety boundary plainly: an approved plan is not a live campaign, and a brief is not a published asset.diff --git a/paid-ads/paid-ads-integrations/SKILL.md b/paid-ads/paid-ads-integrations/SKILL.mdindex 506afd4b..c894d517 100644--- a/paid-ads/paid-ads-integrations/SKILL.md+++ b/paid-ads/paid-ads-integrations/SKILL.md@@ -10,7 +10,7 @@ Read `../shared/operating-contract.md`. Treat tool discovery as the source of tr## Verify before promising-1. Inspect the available tool list. On the universal NotFair MCP, call `listConnectedPlatforms` first. Use the Google or Meta shared preamble when that surface is requested; for X Ads and LinkedIn Ads, resolve the platform-prefixed tools and require a harmless account/setup read before claiming access.+1. Follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md). Use its current instructions and capability descriptions to choose tools, and verify the requested platform and account from live data. Do not infer access from another connected platform.2. Confirm OAuth/account access with a harmless account-list or read operation when the connector exposes one.3. Record the exact platform, selected account, accessible date range, and whether the surface is read-only or mutation-capable.4. If authorization fails, state the error and give the documented connection path. Do not retry a destructive operation or fall back to another account.diff --git a/paid-ads/paid-ads-linkedin/SKILL.md b/paid-ads/paid-ads-linkedin/SKILL.mdindex bda0d8e1..c7819358 100644--- a/paid-ads/paid-ads-linkedin/SKILL.md+++ b/paid-ads/paid-ads-linkedin/SKILL.md@@ -6,11 +6,11 @@ argument-hint: "<B2B goal, audience, account, or date range>"# LinkedIn Ads-Read `../shared/operating-contract.md` and `../shared/measurement-framework.md` before acting. Prefer the `linkedin_ads_` tools on the universal NotFair MCP; use a supplied export only when no verified connector is available.+Read `../shared/operating-contract.md` and `../shared/measurement-framework.md` before acting. Use live account data from the connected platform; use a supplied export when no verified connector is available.## Establish access and qualified-demand context-1. Resolve `~~linkedin-ads` to the universal connector's `linkedin_ads_` tool surface or a verified compatible connector. Call `listConnectedPlatforms` when using NotFair, then confirm the selected account with a harmless account/setup read. Do not infer LinkedIn access from another platform's tools.+1. Follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md). Resolve `~~linkedin-ads` to the live connection. Use its current instructions and capability descriptions to choose tools, and verify the requested platform and account from live data. Do not infer access from another connected platform.2. If the connector is missing or unauthorized, request re-authorization or a current export and keep the result plan/review-only.3. Define the sales-qualified conversion, CRM feedback loop, account currency, attribution basis, target CPA or pipeline outcome, and complete date window before diagnosing performance.@@ -18,7 +18,7 @@ Keep lead quantity separate from lead quality. Build targeting hypotheses from j## Read and diagnose-Use `runScript` for correlated read-only work across campaign groups, campaigns, creatives, and analytics. Prefer a single broad read. Use specialized point tools for individual objects, conversion rules, lead forms, targeting lookup, or lead-form responses.+Correlate campaign groups, campaigns, creatives, and analytics as needed. Choose available capabilities for individual objects, conversion rules, lead forms, targeting information, or lead responses; retrieve only what the question needs.Interpret the platform correctly:diff --git a/paid-ads/paid-ads-setup/SKILL.md b/paid-ads/paid-ads-setup/SKILL.mdindex 4a4bf0e1..825686bd 100644--- a/paid-ads/paid-ads-setup/SKILL.md+++ b/paid-ads/paid-ads-setup/SKILL.md@@ -10,7 +10,7 @@ Read `../shared/operating-contract.md`. Do not alter campaigns during setup.## Establish access-1. Detect the requested platform on the universal NotFair MCP. Call `listConnectedPlatforms`, then use the existing shared preambles for Google Ads and Meta Ads or the `x_ads_` and `linkedin_ads_` tool surfaces. If the requested platform is missing, direct the user to connect it in NotFair and stop before claiming access.+1. Follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md). Use its current instructions and capability descriptions to choose tools, and verify the requested platform and account from live data. Do not infer access from another connected platform.2. List only accounts actually returned by the connected surface. Let the user select the intended account when more than one is available; never infer it from an account name.3. For TikTok, Amazon, and ChatGPT Ads, check the available tools before proposing a connection. If no verified connector exists, request a current export or describe the plan-only boundary.diff --git a/paid-ads/paid-ads-x/SKILL.md b/paid-ads/paid-ads-x/SKILL.mdindex 376c09ff..9afbff60 100644--- a/paid-ads/paid-ads-x/SKILL.md+++ b/paid-ads/paid-ads-x/SKILL.md@@ -6,17 +6,17 @@ argument-hint: "<account, campaign, date range, or X Ads goal>"# X Ads-Read `../shared/operating-contract.md` and `../shared/measurement-framework.md` before acting. Use the `x_ads_` tools on the universal NotFair MCP as the source of truth.+Read `../shared/operating-contract.md` and `../shared/measurement-framework.md` before acting. Use the live account data from the connected platform as the source of truth.## Establish the live scope-1. Resolve `~~x-ads` to the universal connector's `x_ads_` tool surface or a verified compatible connector. On the universal connector, call `listConnectedPlatforms` and require X Ads to be connected; do not infer X access from another platform's tools.+1. Follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md). Resolve `~~x-ads` to the live connection. Use its current instructions and capability descriptions to choose tools, and verify the requested platform and account from live data. Do not infer access from another connected platform.2. Confirm the selected account with a harmless account/setup read. If the connector is missing or unauthorized, direct the user to connect or re-authorize X Ads and stop before claiming live access.3. Record the account currency, timezone, objective, conversion definition, attribution basis, and requested date window. Treat tracking gaps as limitations, not zero performance.## Diagnose with one broad read-Use the connector's `runScript` analytics surface for audits and correlated reads. Pull campaigns, line items, funding/configuration, and performance in one pass when possible; use specialized point reads only for one narrow object or for capabilities outside the script sandbox.+Pull the campaigns, line items, funding/configuration, and performance relevant to the question. Choose available read capabilities and batch related data when useful.Interpret the platform correctly:@@ -30,7 +30,7 @@ Lead with the business decision: strongest contributor, largest material risk, l## Execute approved changes safely-Use dedicated mutation tools, never the read-only script surface. Show the exact account, entity, current value, proposed value, spend exposure, risk, and rollback before acting. Prefer a dry-run preview for budget, bid, targeting, optimization-event, and create operations when the connector offers it.+Use a supported write capability and respect its current contract. Show the exact account, entity, current value, proposed value, spend exposure, risk, and rollback before acting. Prefer a dry-run preview for budget, bid, targeting, optimization-event, and create operations when the connector offers it.- Prefer pause/enable over irreversible deletion.- Create campaigns and line items paused, then verify configuration before activation.diff --git a/paid-ads/shared/operating-contract.md b/paid-ads/shared/operating-contract.mdindex 6598f5b8..7a3c0ab8 100644--- a/paid-ads/shared/operating-contract.md+++ b/paid-ads/shared/operating-contract.md@@ -1,6 +1,6 @@# Paid Ads Operating Contract-Read this before any paid-media analysis, recommendation, or mutation.+Read this before any paid-media analysis, recommendation, or mutation. For live NotFair work, follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md). Choose tools from the live connection and verify the requested platform and account. Keep reads and changes within their declared capability boundaries.## Evidence and money@@ -8,7 +8,7 @@ Read this before any paid-media analysis, recommendation, or mutation.2. Verify conversion tracking before declaring a CPA, ROAS, or waste finding actionable. If tracking is unverified, frame performance conclusions as provisional.3. Show the current state, proposed state, daily and implied monthly spend, scope, and expected observation window before a change that can affect delivery or spend.4. Obtain explicit approval for every spend-increasing action, campaign enablement, budget change, bid change, or irreversible deletion. Create campaigns paused where the connected platform supports creation; never assume that a plan is live.-5. Use dedicated mutation tools only. Read the changed entity back and report the confirmed result, including any partial failure.+5. Use capabilities whose current contract supports the requested change. Read the changed entity back and report the confirmed result, including any partial failure.6. Prefer the narrowest reversible intervention. Change one material variable at a time unless the user approves a bundled, clearly itemized operation.## Capability boundarydiff --git a/plugin.json b/plugin.jsonindex ce037abe..712792ba 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.2",+ "version": "0.27.4","description": "Operate ads and analytics, and run open-source SEO, GEO, and content workflows from compatible AI agents.","author": {"name": "NotFair",diff --git a/seo/broken-link-checker/SKILL.md b/seo/broken-link-checker/SKILL.mdindex 55d0764a..a2f73c21 100644--- a/seo/broken-link-checker/SKILL.md+++ b/seo/broken-link-checker/SKILL.md@@ -2,15 +2,15 @@name: broken-link-checkerargument-hint: "<URL to check, e.g. https://example.com>"description: >- Scans a website to find broken links (404s, 500s). Crawls internal pages,+ Scans a website to find broken links (404s, 500s). Crawls internal pages,identifies broken outbound links, and reports source pages for easy fixing.- Use this when the user asks to "check for broken links", "find 404s",+ Use this when the user asks to "check for broken links", "find 404s","audit my links", or "is my site healthy".---# Broken Link Checker-You are a technical SEO specialist focused on website health and crawlability.+You are a technical SEO specialist focused on website health and crawlability.Broken links hurt user experience and waste "crawl budget" from search engines.Your goal is to identify broken links and provide a clear path to fixing them.diff --git a/seo/content-writer/SKILL.md b/seo/content-writer/SKILL.mdindex 3cbf5bd9..37cd1d96 100644--- a/seo/content-writer/SKILL.md+++ b/seo/content-writer/SKILL.md@@ -219,18 +219,12 @@ should be compressed to the displayed size before publishing.### Image generation-Generate the images during the writing step — don't leave them as TODO. Pick the-first surface that's actually available in the current host, in this order:--1. **Codex or other host with native image generation** (gpt-image, Imagen, etc.)- — generate the image inline. Save to `images/` or the path the user specifies.-2. **NotFair MCP `generate_image`** — if the universal NotFair MCP is connected- (`mcp__NotFair__google_ads_generate_image` or `mcp__NotFair__meta_ads_generate_image`, subject to host sanitization),- it generates marketing-grade visuals from a prompt. Works for blog imagery too.-3. **No image-gen surface available** — output the detailed prompt for each image- so the user can run it in their own tool (Midjourney, DALL·E, Figma AI, etc.),- and place the markdown image tag with the planned filename so the post is ready- to drop the asset in.+Generate images using an appropriate image-generation capability available in+the current host or a connected service. Follow its current instructions and+save the outputs to the user's requested location. Do not infer image-generation+support from an MCP server's name. If no such capability is available, provide+the image prompts and clearly label the missing assets; do not claim generation+succeeded.Every image prompt must be specific: subject, style (photographic / 3D render /flat illustration / data viz), composition, color palette, mood, and what todiff --git a/seo/content-writer/references/content-writing.md b/seo/content-writer/references/content-writing.mdindex c2bbd99b..31ebd5f7 100644--- a/seo/content-writer/references/content-writing.md+++ b/seo/content-writer/references/content-writing.md@@ -209,16 +209,11 @@ that determines whether the post gets clicked on social.- The same image used decoratively in every section### Image generation-The agent should generate the images during the writing pass — don't hand the-user a TODO list. Pick the first available surface:--1. **Host-native image gen** (Codex `gpt-image`, Gemini Imagen, etc.) — use it- directly. Save to `images/` or the path the user picks.-2. **NotFair MCP** — if a NotFair MCP is connected, `generate_image` produces- marketing-grade visuals from a prompt; works for blog imagery too.-3. **No image-gen available** — emit the detailed prompt for each image along- with the markdown image tag (with the planned filename) so the post is ready- to slot the asset in.+Use an appropriate image-generation capability available in the host or a+connected service, following its current instructions. Save the generated assets+to the user's chosen location. Do not assume an MCP supports image generation+from its name. If no suitable capability exists, provide detailed prompts and+clearly mark the assets as still needed.### Writing an image promptEvery prompt names: subject, style (photographic / 3D render / flat illustrationdiff --git a/seo/shared/preamble.md b/seo/shared/preamble.mdindex 5c560314..1e3ba0ca 100644--- a/seo/shared/preamble.md+++ b/seo/shared/preamble.md@@ -1,44 +1,25 @@# SEO Shared Preamble-Every SEO skill reads this before doing anything else. It handles script discovery, GSC authentication, and site selection in one place — so individual skills don't repeat this logic.--## Step 1: Check for cached GSC session--If gcloud credentials already exist and the user has previously selected a GSC property in this session, skip to Step 4. Signs of a cached session:-- `gcloud auth application-default print-access-token` succeeds silently-- The target URL is already known from the conversation--If both are true, skip straight to Step 4.--## Step 2: Locate skill scripts--All SEO skills share the scripts in `seo-analysis/scripts/`. Locate them once:--```bash-SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)-[ -z "$SKILL_SCRIPTS" ] && echo "ERROR: seo-analysis scripts not found" && exit 1-```--Use `$SKILL_SCRIPTS` for all subsequent script calls.--## Step 3: Preflight — gcloud and GSC API--Run the preflight check to ensure gcloud is installed, a GCP project exists, and the Search Console API is enabled:--```bash-python3 "$SKILL_SCRIPTS/preflight.py"-```--- **`OK: All dependencies ready.`** — continue to Step 4.-- **Browser opens for Google login** — user needs to log in with the Google account that owns their Search Console properties. Preflight finishes automatically after login.-- **`gcloud init` runs** — first-time user. The wizard walks them through setup. After it completes, preflight continues automatically.-- **`Search Console API: enabled`** — preflight auto-enabled the API. No action needed.-- **ERROR: Could not enable the Search Console API** — user needs to enable manually: `gcloud services enable searchconsole.googleapis.com`-- **gcloud not found** — OS-specific install instructions are printed. Install gcloud, then re-run.-- **No gcloud and user wants to skip GSC** — that is fine. GSC data won't be available, but skills can still operate on URL-only analysis (technical crawl, meta tags, schema).--> **Reference**: For manual setup or troubleshooting, see `../seo-analysis/references/gsc_setup.md`.--## Step 4: Proceed--Scripts are located at `$SKILL_SCRIPTS`, auth is ready. All subsequent script calls in the invoking skill should use `$SKILL_SCRIPTS` directly — do not re-run the find command. Hand control back to the invoking skill.+Match setup to the task. URL-only reviews and supplied exports do not require+Search Console authentication. For live Search Console work, use an available+connector and follow [`../../docs/mcp-connection.md`](../../docs/mcp-connection.md)+for NotFair. Let the connection's current instructions and schemas determine+tool selection, and confirm the intended property from live data.++## Optional local scripts++The repository also provides scripts under `seo/seo-analysis/scripts/` for+crawling, local analysis, and direct Search Console access. Locate them relative+to the installed skill directory and set `SKILL_SCRIPTS` to that directory when a+workflow uses them. Choose the script or connected capability that fits the task;+a script example in a workflow is not a requirement to replace a working MCP.++Only run `preflight.py` when the task actually needs the direct Google API script+path and its dependencies are missing. This path uses gcloud credentials and+Google Cloud setup; it is not required for NotFair MCP access. See+`../seo-analysis/references/gsc_setup.md` for that optional setup. Do not install+additional dependencies or start a second authentication flow just because an+SEO skill was invoked.++If live data is unavailable, explain the gap and continue the portions supported+by the user's URL, repository, or export. Do not present missing data as zero.diff --git a/server-google-ads.json b/server-google-ads.jsondeleted file mode 100644index fc567104..00000000--- a/server-google-ads.json+++ /dev/null@@ -1,18 +0,0 @@-{- "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",- "name": "io.github.nowork-studio/notfair",- "title": "NotFair-GoogleAds",- "description": "Hosted Google Ads MCP with OAuth, 117 tools, MCC routing, image assets, and approval-gated writes.",- "websiteUrl": "https://notfair.co/google-ads-mcp",- "repository": {- "url": "https://github.com/nowork-studio/notfair-plugin",- "source": "github"- },- "version": "0.27.0",- "remotes": [- {- "type": "streamable-http",- "url": "https://notfair.co/api/mcp/google_ads"- }- ]-}diff --git a/server-meta-ads.json b/server-meta-ads.jsondeleted file mode 100644index 3700380d..00000000--- a/server-meta-ads.json+++ /dev/null@@ -1,18 +0,0 @@-{- "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",- "name": "io.github.nowork-studio/notfair-meta-ads",- "title": "NotFair-MetaAds",- "description": "Meta Ads MCP (Facebook + Instagram) - analyze performance, manage budgets, pause campaigns.",- "websiteUrl": "https://notfair.co",- "repository": {- "url": "https://github.com/nowork-studio/notfair-plugin",- "source": "github"- },- "version": "0.1.0",- "remotes": [- {- "type": "streamable-http",- "url": "https://notfair.co/api/mcp/meta_ads"- }- ]-}diff --git a/server.json b/server.jsonindex b196b707..f854d638 100644--- a/server.json+++ b/server.json@@ -2,13 +2,13 @@"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","name": "io.github.nowork-studio/notfair","title": "NotFair",- "description": "Hosted OAuth MCP for Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Search Console, Google Analytics 4, and GoHighLevel.",+ "description": "OAuth MCP for Google, Meta, X and LinkedIn Ads, Search Console, GA4 and GoHighLevel.","websiteUrl": "https://notfair.co","repository": {"url": "https://github.com/nowork-studio/notfair-plugin","source": "github"},- "version": "0.27.2",+ "version": "0.27.4","remotes": [{"type": "streamable-http",diff --git a/skills/google-ads-audit/SKILL.md b/skills/google-ads-audit/SKILL.mdindex 5ed28630..14820f5c 100644--- a/skills/google-ads-audit/SKILL.md+++ b/skills/google-ads-audit/SKILL.md@@ -1,6 +1,6 @@---name: google-ads-audit-description: Google Ads account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other ads skills reuse. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to NotFair and hasn't run an audit before. Also trigger proactively when other ads skills detect that business-context.json is missing.+description: Google Ads account audit and business context setup. Use for account-health audits and business-context setup. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to NotFair and hasn't run an audit before.argument-hint: "<account name or 'audit my ads'>"---diff --git a/skills/meta-ads-audit/SKILL.md b/skills/meta-ads-audit/SKILL.mdindex 57a8a5ff..123948b2 100644--- a/skills/meta-ads-audit/SKILL.md+++ b/skills/meta-ads-audit/SKILL.md@@ -1,6 +1,6 @@---name: meta-ads-audit-description: Meta Ads (Facebook + Instagram) account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other Meta ads skills reuse. Trigger on "audit my Meta ads", "audit my Facebook ads", "Meta ads audit", "set up my Meta ads", "onboard Meta", "Meta account overview", "how's my Meta account", "Meta health check", "what should I fix in my Facebook ads", or when the user is new to NotFair Meta and hasn't run an audit before. Also trigger proactively when other Meta ads skills detect that meta business-context.json is missing.+description: Meta Ads (Facebook + Instagram) account audit and business context setup. Use for account-health audits and business-context setup. Trigger on "audit my Meta ads", "audit my Facebook ads", "Meta ads audit", "set up my Meta ads", "onboard Meta", "Meta account overview", "how's my Meta account", "Meta health check", "what should I fix in my Facebook ads", or when the user is new to NotFair Meta and hasn't run an audit before.argument-hint: "<account name or 'audit my Meta ads'>"---diff --git a/test/install.test.sh b/test/install.test.shindex 3c807ab3..2d9c0b97 100755--- a/test/install.test.sh+++ b/test/install.test.sh@@ -274,7 +274,7 @@ echo ""echo "=== 5. MCP server config ==="assert_file "$REPO_ROOT/.codex-plugin/plugin.json" "Codex plugin manifest exists"-assert_contains "$REPO_ROOT/.codex-plugin/plugin.json" '"mcpServers": "./mcp.json"' "Codex manifest loads the portable MCP config"+assert_contains "$REPO_ROOT/.codex-plugin/plugin.json" '"mcpServers": "./.mcp.json"' "Codex manifest loads the native MCP config"assert_contains "$REPO_ROOT/.codex-plugin/plugin.json" '"skills": "./skills/"' "Codex manifest loads the canonical skill index"assert_contains "$REPO_ROOT/.mcp.json" "\"NotFair\"" ".mcp.json registers the universal NotFair server"assert_contains "$REPO_ROOT/.mcp.json" "\"type\": \"http\"" ".mcp.json uses native HTTP transport (no mcp-remote bridge)"diff --git a/test/test_mcp_skill_e2e.py b/test/test_mcp_skill_e2e.pyindex 358359d0..e9141327 100644--- a/test/test_mcp_skill_e2e.py+++ b/test/test_mcp_skill_e2e.py@@ -22,19 +22,14 @@ UNIVERSAL_SERVER = "NotFair"UNIVERSAL_ENDPOINT = "https://notfair.co/api/mcp/notfair"PLATFORM_SKILLS = {- "paid-ads/paid-ads-x": ("~~x-ads", "x_ads_"),- "paid-ads/paid-ads-linkedin": ("~~linkedin-ads", "linkedin_ads_"),- "analytics/search-console": ("~~search-console", "search_console_"),- "analytics/google-analytics": ("~~google-analytics", "google_analytics_"),-}--UNIVERSAL_PREFLIGHTS = {- "google-ads/shared/preamble.md": "google_ads_listConnectedAccounts",- "meta-ads/shared/preamble.md": "meta_ads_listAdAccounts",+ "paid-ads/paid-ads-x": "~~x-ads",+ "paid-ads/paid-ads-linkedin": "~~linkedin-ads",+ "analytics/search-console": "~~search-console",+ "analytics/google-analytics": "~~google-analytics",}-def test_universal_mcp_is_the_only_registered_server_and_skills_use_platform_prefixes():+def test_universal_mcp_is_the_only_registered_server_and_skills_are_portable():config = json.loads((ROOT / ".mcp.json").read_text())plugin = json.loads((ROOT / ".claude-plugin/plugin.json").read_text())codex_plugin = json.loads((ROOT / ".codex-plugin/plugin.json").read_text())@@ -45,7 +40,7 @@ def test_universal_mcp_is_the_only_registered_server_and_skills_use_platform_pre}assert codex_plugin["name"] == "notfair"assert codex_plugin["skills"] == "./skills/"- assert codex_plugin["mcpServers"] == "./mcp.json"+ assert codex_plugin["mcpServers"] == "./.mcp.json"assert codex_plugin["version"] == plugin["version"]codex_wrappers = {path.name: path for path in (ROOT / "skills").iterdir()}@@ -62,29 +57,65 @@ def test_universal_mcp_is_the_only_registered_server_and_skills_use_platform_precanonical_rel = canonical.relative_to(ROOT).as_posix()assert f"../../{canonical_rel}/SKILL.md" in wrapper_text- for skill, (placeholder, platform_prefix) in PLATFORM_SKILLS.items():+ for skill, placeholder in PLATFORM_SKILLS.items():skill_path = ROOT / skill / "SKILL.md"assert skill_path.is_file()skill_text = skill_path.read_text()assert placeholder in skill_text- assert platform_prefix in skill_textassert f"./{skill}" in plugin["skills"]- for preamble, gated_account_tool in UNIVERSAL_PREFLIGHTS.items():- preamble_text = (ROOT / preamble).read_text()- preflight = "call `listConnectedPlatforms` **before**"- disconnected_stop = f"do not call `{gated_account_tool}`"- assert preflight in preamble_text- assert disconnected_stop in preamble_text- assert preamble_text.index(preflight) < preamble_text.index(disconnected_stop)++def test_all_host_configs_and_registry_use_one_versioned_connection():+ expected = {UNIVERSAL_SERVER: {"type": "http", "url": UNIVERSAL_ENDPOINT}}+ version = (ROOT / "VERSION").read_text().strip()+ for config in (".mcp.json", "mcp.json", "gemini-extension.json"):+ assert json.loads((ROOT / config).read_text())["mcpServers"] == expected+ for manifest in (+ ".claude-plugin/plugin.json", ".codex-plugin/plugin.json",+ ".cursor-plugin/plugin.json", "plugin.json", "gemini-extension.json",+ "server.json",+ ):+ assert json.loads((ROOT / manifest).read_text())["version"] == version+ for manifest in (".codex-plugin/plugin.json", ".cursor-plugin/plugin.json"):+ config_path = json.loads((ROOT / manifest).read_text())["mcpServers"]+ assert json.loads((ROOT / config_path).read_text())["mcpServers"] == expected+ marketplace = json.loads((ROOT / ".claude-plugin/marketplace.json").read_text())+ assert marketplace["metadata"]["version"] == version+ assert marketplace["plugins"][0]["version"] == version+ registry = json.loads((ROOT / "server.json").read_text())+ assert 1 <= len(registry["description"]) <= 100+ assert registry["remotes"] == [{"type": "streamable-http", "url": UNIVERSAL_ENDPOINT}]+ assert list(ROOT.glob("server*.json")) == [ROOT / "server.json"]+ workflow = (ROOT / ".github/workflows/mcp-registry-publish.yml").read_text()+ assert "validate server.json" in workflow+ assert "publish server.json" in workflow+++def test_active_plugin_files_do_not_advertise_legacy_endpoints():+ # Historical release notes and the separately shipped local app are not+ # plugin installation configuration. Inspect every active plugin surface.+ roots = [ROOT / name for name in (+ "README.md", "AGENTS.md", "CLAUDE.md", "INSTALL_FOR_AGENTS.md",+ "docs", "install", "paid-ads", "google-ads", "meta-ads", "analytics", "seo",+ ".claude-plugin", ".codex-plugin", ".cursor-plugin", ".github",+ ".mcp.json", "mcp.json", "server.json", "gemini-extension.json",+ )]+ for root in roots:+ for path in (root.rglob("*") if root.is_dir() else [root]):+ if not path.is_file() or path.suffix not in {".md", ".json", ".yml", ".sh"}:+ continue+ text = path.read_text()+ for url in re.findall(r"https://(?:www\.)?notfair\.co/api/mcp[^\s\"`<>)]*", text):+ assert url == UNIVERSAL_ENDPOINT, (path, url)@pytest.mark.skipif(os.environ.get("LIVE_MCP_E2E") != "1",reason="Set LIVE_MCP_E2E=1 to verify production OAuth discovery",)-def test_live_mcp_oauth_discovery_round_trip():- endpoint = UNIVERSAL_ENDPOINT[email protected]("origin", ["https://notfair.co", "https://www.notfair.co"])+def test_live_mcp_oauth_discovery_round_trip(origin):+ endpoint = f"{origin}/api/mcp/notfair"request = urllib.request.Request(endpoint,headers={"Accept": "application/json, text/event-stream"},@@ -108,7 +139,7 @@ def test_live_mcp_oauth_discovery_round_trip():metadata = json.load(metadata_response)assert metadata["resource"] == endpoint- assert metadata["authorization_servers"] == ["https://notfair.co"]+ assert metadata["authorization_servers"] == [origin]assert metadata["resource_name"] == "NotFair"authorization_server = metadata["authorization_servers"][0]