Open-source SEO, GEO, and marketing skills for AI agents.
docs: introduce NotFair CMO in the README
Yuting Zhong6e2be04a54c0
diff --git a/README.md b/README.mdindex 2de94f40..b55b2aff 100644--- a/README.md+++ b/README.md@@ -6,10 +6,12 @@NotFair gives your AI agent direct access to Google Search Console, Google Ads, and Meta Ads (Facebook + Instagram). It analyzes your traffic, surfaces what's hurting your rankings, finds wasted ad spend, diagnoses creative fatigue and audience saturation, and tells you exactly what to fix. When you have access to the repo, it goes further: rewriting meta tags, fixing headings, adding structured data, and shipping the changes.-### CLI + web — same engine+### CLI + web + local portal — same engineThe NotFair plugin is the CLI side — the skills that run inside Claude Code (and other AI agent hosts). [notfair.co](https://notfair.co) is the companion web app: sign in once, connect your Google Ads and Meta Ads accounts, and run audits through a browser UI. Both sides share the same engine, so an audit you run from the CLI uses the same tooling as the one on the web.+There's also **[NotFair CMO](#notfair-cmo--a-local-marketing-team-in-your-browser)** — a local web portal that runs a team of specialist marketing agents (CMO, Google Ads, Meta Ads, SEO, X Ads) on top of your existing Claude Code or Codex login.+> *"Am I wasting money on ads right now?"*> *"Why did my traffic drop and how do I fix it?"*> *"How do I get more conversions without spending more?"*@@ -160,6 +162,29 @@ The plugin was renamed `toprank` → `notfair` in v0.24.0. If you previously insYour data is preserved — the runtime state directory (`~/.toprank/`, holding portfolio state, change logs, business-context cache, audit history) is intentionally retained under its original name for this release. See `CHANGELOG.md` for details.+---++## NotFair CMO — a local marketing team in your browser++[NotFair CMO](notfair-cmo/) is a local web portal that turns the skills above into an always-on marketing team. Instead of invoking skills one at a time from the CLI, you get named specialist agents per project — a **CMO** who owns strategy and delegates, plus **Google Ads**, **Meta Ads**, **SEO**, and **X Ads** specialists — each in its own isolated workspace, running on top of the Claude Code or Codex login you already have. Chat with them, watch tasks move across a kanban board, approve governed actions (spend, publishes, bid changes) from an approvals inbox, and let them schedule their own recurring jobs on a native cron scheduler.++Open source, runs entirely on your machine, published to npm as [`notfair-cmo`](https://www.npmjs.com/package/notfair-cmo).++### Get started++**Prerequisites:** Node 20+ and at least one harness installed and authenticated — [Claude Code](https://docs.claude.com/en/docs/agents-and-tools/claude-code/overview) (recommended) or [Codex CLI](https://github.com/openai/codex).++```bash+npx notfair-cmo@latest doctor # preflight: Node, harnesses, data dir, port+npx notfair-cmo@latest # launch the UI at http://127.0.0.1:3327+```++Or install globally with `npm install -g notfair-cmo`, then run `notfair-cmo`.++Create a project, pick your harness, and connect platforms during onboarding — each MCP you connect (Google Ads, Meta Ads, Search Console, X Ads) provisions the matching specialist agent automatically. Already using the plugin? `/notfair:cmo` launches the portal straight from Claude Code.++Full docs, CLI reference, and architecture notes: [`notfair-cmo/README.md`](notfair-cmo/README.md).+## Skills### Google Ads@@ -232,6 +257,7 @@ notfair/│ ├── geo-optimizer/ <- GEO for AI search engines│ └── setup-cms/ <- CMS connector├── gemini/ <- cross-model review via Gemini CLI+├── notfair-cmo/ <- local marketing portal (npm: notfair-cmo)├── notfair-upgrade-skill/ <- self-updater├── test/ <- unit + LLM-judge eval tests└── VERSIONdiff --git a/notfair-cmo/README.md b/notfair-cmo/README.mdindex c1677880..eabfd396 100644--- a/notfair-cmo/README.md+++ b/notfair-cmo/README.md@@ -7,7 +7,7 @@ Open source. Runs entirely on your machine. Bring your own LLM credentials (via## What it gives you- **Per-agent chat** scoped to each project — talk to a marketing-shaped agent that can launch campaigns, audit SEO, propose recurring jobs. Tool calls + MCP invocations stream inline as collapsible step rows.-- **Specialist agents** (CMO + Google Ads + SEO) auto-provisioned per project, isolated in their own workspace dir. Clone or create more from the sidebar.+- **Specialist agents** (CMO + Google Ads + Meta Ads + SEO + X Ads), each isolated in its own workspace dir. The CMO is provisioned on project create; each specialist appears when you connect the matching platform MCP. Clone or create more from the sidebar.- A **cron tab** (calendar + list) backed by a native SQLite scheduler. Agents create jobs via the `schedule_recurring_work` MCP tool; the tick loop in the Next.js process fires them on time.- **Project-scoped MCP connections** — one-click PKCE OAuth to bring third-party tools (Google Ads via NotFair's hosted MCP) into the agents' toolbox. Tokens stored in SQLite, never in env vars, and wired into the chosen harness automatically.- A **live audit log** of every autonomous decision and scheduled run, append-only.@@ -65,10 +65,11 @@ Options on `doctor`: `--port <n>`, `--data-dir <path>`.## What happens when you create a project1. SQLite row written at `~/.notfair-cmo/db.sqlite` with your harness choice (`projects.harness_adapter`).-2. Default agents provisioned under the project's slug:- - `<slug>-cmo-<name>` — Chief Marketing Officer- - `<slug>-google-ads-<name>` — Google Ads specialist- - SEO is opt-in, provisioned on demand.+2. Agents provisioned under the project's slug:+ - `<slug>-cmo-<name>` — Chief Marketing Officer, created immediately.+ - Specialists (`google-ads`, `meta-ads`, `seo`, `x-ads`) are gated on+ connecting the matching platform MCP — each OAuth connect provisions+ its agent (Search Console provisions the SEO specialist).Each gets its own workspace at `~/.notfair-cmo/agents/<id>/` with an `IDENTITY.md` system prompt scoped to its role + the chosen harness's native config (`.mcp.json` for Claude Code, sections in `~/.codex/config.toml` for Codex).3. The orchestration MCP server (`/api/mcp/orchestration`) is registered for every agent so they can call `create_task`, `submit_task_status`, `set_project_brief`, `schedule_recurring_work`, etc.@@ -82,7 +83,7 @@ You can also schedule manually via the **+ New cron** button on the Crons tab.## Connecting MCP servers (for live ad-platform data)-The Connections page lists the MCP servers in our catalog (currently: NotFair Google Ads). Click **Connect** to start a one-click PKCE OAuth flow — no environment variables to set, no Google Cloud project of your own to register.+The Connections page lists the MCP servers in our catalog (NotFair Google Ads, Meta Ads, Google Search Console, Google Analytics, X Ads — plus browseable extras like Stripe and Supabase, or any custom MCP URL). Click **Connect** to start a one-click PKCE OAuth flow — no environment variables to set, no Google Cloud project of your own to register.The token is persisted into `mcp_tokens` (SQLite) and the catalog MCP is automatically registered with every agent in the project via the chosen harness's config. New agents provisioned later get the same wiring.