Open-source SEO, GEO, and marketing skills for AI agents.
docs: update NotFair READMEs (#96)
Yuting Zhongfed15da931e9
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex e19bc20a..3fdadba1 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO, GEO, Google Ads, and Meta Ads skills for Claude Code.",- "version": "0.25.6"+ "version": "0.25.7"},"plugins": [{"name": "notfair","source": "./","description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, GSC-driven content planning + local calendar viewer, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",- "version": "0.25.6",+ "version": "0.25.7","author": {"name": "NotFair","url": "https://notfair.co"diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 9e84646d..118cd873 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.25.6",+ "version": "0.25.7","description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.","author": {"name": "NotFair",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3b543580..c488bed4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,16 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).---+## [0.25.7] — 2026-07-14++### Changed++- Updated the public skill catalog to include the GSC-driven content planner and NotFair upgrade skill, and clarified that compatible coding agents can discover the host-agnostic skills through `AGENTS.md`.+- Brought the local NotFair app documentation in line with the shipped goal lifecycle, Codex account and model UI, platform selection, pull-request workflow, supported npm platform, and lowercase CLI commands.+- Documented the app's current trust boundaries accurately: Codex runs as trusted unsandboxed local automation, workflow and pull-request limits are behavioral guardrails, and OAuth credentials are not yet encrypted at the application layer.++---+## [0.25.6] — 2026-06-04### Addeddiff --git a/README.md b/README.mdindex 32722da1..9e7cdeaa 100644--- a/README.md+++ b/README.md@@ -166,13 +166,13 @@ Your data is preserved — the runtime state directory (`~/.toprank/`, holding p## The NotFair app — goal-driven marketing agents in your browser-[NotFair](notfair/) is a local web portal built around one idea: state a goal, get a loop. A dedicated agent turns your ambition into a server-verified metric with a measured baseline, you confirm the target, and the agent runs a disciplined improvement cycle on your cadence — the platform measures the number mechanically each tick, the agent scores its past moves against their predictions, makes at most one new move, and every governed action (spend, publishes, bid changes) parks in an approvals inbox until you decide. The Goal page shows the whole loop: metric sparkline vs. target, tick diary, open actions with review dates, and the learnings the agent accumulates.+[NotFair](notfair/) is a local web portal built around one idea: state a goal, get a loop. A dedicated agent turns your ambition into a server-verified metric with a measured baseline, you confirm the target, and the agent runs a disciplined improvement cycle on your cadence — the platform measures the number mechanically each tick, the agent scores its past moves against their predictions, and the goal protocol limits it to one new move. The protocol requires mutations to be logged with observation windows that gate affected resources in future turns; code changes go through a branch and a GitHub pull request for you to review and merge. These are behavioral guardrails for trusted local automation, not an OS-level security sandbox. The Goal page shows the whole loop: metric sparkline vs. target, tick diary, open actions with review dates, and the learnings the agent accumulates.Open source, runs entirely on your machine, published to npm as [`notfair`](https://www.npmjs.com/package/notfair).### 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).+**Prerequisites:** An Apple Silicon Mac, Node 20+, and at least one harness installed and authenticated — [Codex CLI](https://github.com/openai/codex) (recommended) or [Claude Code](https://docs.claude.com/en/docs/agents-and-tools/claude-code/overview). The published npm package currently declares support for macOS on ARM64 only.```bashnpx notfair@latest doctor # preflight: Node, harnesses, data dir, port@@ -181,7 +181,9 @@ npx notfair@latest # launch the UI at http://127.0.0.1:3327Or install globally with `npm install -g notfair`, then run `notfair`.-Create a project, pick your harness, connect platforms during onboarding, then open **Goal** and state an ambition — the agent works out how to measure it and shows you the baseline before anything runs. Already using the plugin? `/notfair:cmo` launches the portal straight from Claude Code.+The current `doctor` command reports each harness separately and exits non-zero when either Claude Code or Codex is absent, even though the app itself only requires the harness selected for that project.++Create a project, optionally attach a codebase, pick your harness, connect platforms and choose the relevant account during onboarding, then state your first ambition. NotFair creates the goal's agent internally, works out how to measure the goal, and shows you the baseline and target before anything runs. The Codex sidebar reports the signed-in account's plan and usage, while model selectors show the configured model name instead of a generic default label.Full docs, CLI reference, and architecture notes: [`notfair/README.md`](notfair/README.md).@@ -209,6 +211,7 @@ Full docs, CLI reference, and architecture notes: [`notfair/README.md`](notfair/|-------|-------------|| [`seo-analysis`](seo/seo-analysis/) | Full SEO audit with GSC data. Quick wins, traffic drops, technical issues, 30-day action plan. || [`content-writer`](seo/content-writer/) | SEO content creation following E-E-A-T guidelines. Blog posts, landing pages, content improvements. |+| [`content-planner`](seo/content-planner/) | Builds a dated editorial calendar from real Search Console opportunities, prioritized by click potential and ready to hand to `content-writer`. || [`keyword-research`](seo/keyword-research/) | Keyword discovery, intent classification, topic clusters, prioritized content calendar. || [`meta-tags-optimizer`](seo/meta-tags-optimizer/) | Title tags, meta descriptions, OG/Twitter cards with A/B variations and CTR estimates. || [`schema-markup-generator`](seo/schema-markup-generator/) | JSON-LD structured data for rich results. FAQ, HowTo, Article, Product, LocalBusiness. |@@ -223,20 +226,26 @@ Full docs, CLI reference, and architecture notes: [`notfair/README.md`](notfair/|-------|-------------|| [`gemini`](gemini/) | Second opinion from Google Gemini. Review (pass/fail gate), challenge (adversarial stress test), or consult (open Q&A). Especially strong on Google Ads and SEO decisions — Gemini has native Google ecosystem knowledge. |+### Maintenance++| Skill | What it does |+|-------|-------------|+| [`upgrade`](notfair-upgrade-skill/) | Updates an installed NotFair plugin to the latest marketplace release and summarizes what changed. |+All skills are namespaced: `/notfair:google-ads`, `/notfair:seo-analysis`, `/notfair:gemini`, etc.---## How It Works-NotFair is a Claude Code plugin. Each skill is a `SKILL.md` file with supporting reference documents, scripts, and eval tests.+NotFair ships as a Claude Code plugin, while the skill directories themselves are host-agnostic and discoverable by compatible coding agents through [`AGENTS.md`](AGENTS.md). Each skill is a `SKILL.md` file with supporting reference documents, scripts, and eval tests.```notfair/├── .claude-plugin/│ ├── plugin.json <- plugin metadata (explicit skill paths)│ └── marketplace.json <- registry entry-├── .mcp.json <- NotFair MCP servers (Google Ads + Meta Ads, auto-configured)+├── .mcp.json <- NotFair MCP servers (Google Ads + Meta Ads + Search Console)├── google-ads/│ ├── manage/ <- campaign management (skill: google-ads)│ ├── audit/ <- account audit + business context@@ -249,6 +258,7 @@ notfair/├── seo/│ ├── seo-analysis/ <- full SEO audit with GSC data│ ├── content-writer/ <- E-E-A-T content creation+│ ├── content-planner/ <- GSC-driven editorial calendar│ ├── keyword-research/ <- keyword discovery + topic clusters│ ├── meta-tags-optimizer/ <- title tags, meta descriptions, OG│ ├── schema-markup-generator/ <- JSON-LD structured datadiff --git a/VERSION b/VERSIONindex 3f44db94..d8980711 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.25.6+0.25.7diff --git a/notfair/README.md b/notfair/README.mdindex 1c16d22b..51326598 100644--- a/notfair/README.md+++ b/notfair/README.md@@ -7,12 +7,14 @@ Open source. Runs entirely on your machine. Bring your own LLM credentials (via## What it gives you- **Goals are the identity.** Type the ambition, and you land in a chat where the goal's agent is already working: it sharpens the ask, labels the goal ("Wasted X spend → $0"), authors + tests a metric query against your connected platforms, and the platform *re-runs the query server-side* — only a reproducible number with a measured baseline goes on the books. You agree the target in chat; the loop starts only when you press **START** (and the first tick runs immediately). Two modes: **achieve** (reach the number, done) and **maintain** (hold it there forever — a watchdog).-- **The tick loop.** On the cadence you agree, the platform measures the metric mechanically (the agent never self-reports the number it's judged on) and wakes the agent: it scores past moves against their predicted effects, then makes at most **one** new move — every mutation logged with a falsifiable expected effect and an observation window that gates its resources until review. The agent's page is the diary: sparkline vs. target, tick-by-tick log, open actions, accumulated memory.-- **Fully autonomous, visibly so.** No approval inbox — agents act inside a spend envelope you set, with the observation-window discipline and your pause button as the controls, and every move on the record.+- **Platform-focused onboarding.** Connect the data sources a goal needs, choose the relevant account or property, and tag the goal with its platform focus. The focus guides the intake conversation and metric design; every project connection is still wired to every goal agent.+- **The tick loop.** On the cadence you agree, the platform measures the metric mechanically (the agent never self-reports the number it's judged on) and wakes the agent: it scores past moves against their predicted effects, then the protocol allows at most **one** new move and requires a log entry with a falsifiable expected effect and observation window. Future goal turns use those records to avoid gated resources until review. The agent's page is the diary: sparkline vs. target, tick-by-tick log, open actions, accumulated memory.+- **Fully autonomous, visibly so.** No approval inbox — agents are instructed to act inside the spend envelope you set, with observation-window discipline, a pause button for scheduled work, and their recorded moves visible in the app. These are workflow controls for a trusted harness, not a sandbox against arbitrary local commands.+- **Code changes through pull requests.** Attach a GitHub-backed codebase and an agent can work in its own branch, commit and push the change, then register the pull request with NotFair. The app tracks the PR, while its goal protocol instructs the agent to leave merge decisions to you and keep one code mutation in flight at a time. Those rules are prompt-level guardrails, not mechanically enforced permissions.- **Shared context + private memory.** `PROJECT.md` is the workspace brief every agent carries (any agent can update it via `set_shared_context`); each agent also keeps its own learnings ledger and workspace files. All connected MCPs are shared by every agent.- **One screen per goal.** The conversation and the loop's state live together: chat on the left (where the goal is defined and steered), a status rail on the right — the progress chart, the plan, every check with its full log, open actions with review dates, and the agent's memory. No tabs, no thread management, nothing else to learn.- **Progress you can see.** A time-true chart with the target line, every agent action as a marker on the moment it happened (hover: what it did, what it predicted, what actually happened), observation windows shaded, and history backfilled at setup from the platform's own date-segmented stats — context from day one. Maintain goals get a streak ("held at target for 12 days") with a per-check strip; the workspace index shows a mini sparkline + 7-day delta per goal.-- **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.+- **Project-scoped MCP connections** — one-click PKCE OAuth brings third-party tools (Google Ads via NotFair's hosted MCP) into the agents' toolbox. Connection records are stored in local SQLite and wired into the chosen harness automatically; Codex receives bearer tokens through per-server environment variables at process launch.## Pick your harness@@ -20,19 +22,20 @@ At onboarding you pick which local AI coding agent runs the work:| Harness | Status | Notes ||---|---|---|-| **Claude Code** | Recommended | Uses your existing `claude` login. Per-agent `.mcp.json` for isolation. |-| **Codex** | Supported | Uses your existing `codex` login. Per-server env-var bearers. Requires `--dangerously-bypass-approvals-and-sandbox` (set by the adapter) so tool calls and loopback reach your local orchestration MCP. |+| **Codex** | Recommended | Uses your existing `codex` login. Per-server env-var bearers. The sidebar reports the authenticated account's plan and usage, and model selectors show the configured model name. The adapter launches Codex with `--dangerously-bypass-approvals-and-sandbox`; that process inherits the parent environment and can access files available to your local user. Treat goal agents as trusted local automation. |+| **Claude Code** | Supported | Uses your existing `claude` login. Per-agent `.mcp.json` for isolation. |Different projects can run on different harnesses; the choice persists on the project row.## Prerequisites+- **Apple Silicon Mac.** The published npm package currently declares `darwin`/`arm64` support only.- **Node 20+** (Node 24 recommended for native-module prebuilds).- **At least one harness installed and authenticated**:- [Claude Code](https://docs.claude.com/en/docs/agents-and-tools/claude-code/overview), or- [Codex CLI](https://github.com/openai/codex)-Run `NotFair doctor` to verify Node, both harnesses, data dir, and port.+Run `notfair doctor` to check Node, both harness binaries, the data directory, and the port. The current command exits non-zero when either Claude Code or Codex is missing, even though the app itself only needs the harness selected for the project.## Install + run@@ -43,7 +46,7 @@ npx notfair@latest # launch UI on http://127.0.0.1:3327# Or install globally:npm install -g notfair-NotFair+notfair```The UI opens in your browser. Sidebar is project-scoped; create one to start.@@ -51,35 +54,35 @@ The UI opens in your browser. Sidebar is project-scoped; create one to start.## CLI```-NotFair Launch local server + open UI (default)-NotFair start Same as above-NotFair doctor Run preflight checks (see below)-NotFair --version-NotFair --help+notfair Launch local server + open UI (default)+notfair start Same as above+notfair doctor Run preflight checks (see below)+notfair --version+notfair --help```Options on `start`: `--port <n>` (default 3327), `--no-open`, `--data-dir <path>`.Options on `doctor`: `--port <n>`, `--data-dir <path>`.-`doctor` runs five checks: Node ≥ 20 (24 recommended), Claude Code on PATH, Codex on PATH, at least one harness ready, data dir writable, and the preferred port free. Exits 0 if every check is passing, 1 otherwise, with a `Fix:` line under each failure naming the exact command to run.+`doctor` checks Node ≥ 20 (24 recommended), Claude Code on PATH, Codex on PATH, at least one harness ready, a writable data directory, and a free preferred port. It exits 0 if every check is passing and 1 otherwise, with a `Fix:` line under each failure naming the exact command to run.## What happens when you create a goal-1. You name an agent on the workspace page — a goal row (status `intake`) and the agent's workspace at `~/.notfair/agents/<slug>-goal-<name>/` are created together, with an `IDENTITY.md` carrying the goal spec + the loop protocol, mirrored into the harness's native config (`CLAUDE.md` / `AGENTS.md`, `.mcp.json` for Claude Code, sections in `~/.codex/config.toml` for Codex). Every connected MCP is wired in.-2. You chat: the agent records the ambition (`define_goal`), authors + tests a metric query, submits it (`propose_goal_metric` — the platform re-runs it server-side and stores the measured baseline), and, once you explicitly confirm the target, starts the loop (`activate_goal`).-3. The heartbeat rides a `setInterval` in the Next.js process polling every 30 s; due goals get a tick — metric measured, brief composed from the DB, one adapter turn, diary row written.+1. You type a goal statement and can select its platform focus. NotFair creates the goal row (status `intake`), provisions an anonymous goal agent, and creates its workspace at `~/.notfair/agents/<agent-id>/`. The goal protocol is mirrored into the harness's native config (`CLAUDE.md` / `AGENTS.md`, `.mcp.json` for Claude Code, sections in `~/.codex/config.toml` for Codex), with the project's connected MCPs wired in.+2. You chat while the agent records the ambition (`define_goal`), authors and tests a metric query, submits it (`propose_goal_metric` — the platform re-runs it server-side and stores the measured baseline), then proposes the measured target (`propose_target`). The loop does not activate itself: you press **START**, and the first tick runs immediately.+3. The heartbeat rides a `setInterval` in the Next.js process polling every 30 seconds. Due goals get a tick: the metric is measured, a brief is composed from the database, one adapter turn runs, and the diary row is written. A completed check opens as a static log instead of remaining in a streaming state.-## Scheduling recurring work+## Code changes through pull requests-Beyond goal heartbeats, agents can call the `schedule_recurring_work` MCP tool for auxiliary cron jobs, and you can schedule manually via the **+ New cron** button on the Crons tab. Same 30 s tick loop, same per-project harness dispatch.+Attach a local Git repository to the project in **Settings → Codebase**. When a goal requires source changes, the agent works in a dedicated worktree and branch, commits and pushes its changes, opens a GitHub pull request, and registers it with NotFair. Pull-request state is synchronized back into the goal. The goal protocol tells the agent not to merge its own PR or begin a second code mutation before the first is resolved, but the unsandboxed harness can technically run those commands; review the branch and PR as you would any other trusted local automation.## Connecting MCP servers (for live ad-platform data)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.+Connections that expose multiple accounts or properties let you choose and later switch the active selection from the Connections page. Goals use that project-scoped selection when querying the platform.-OAuth refresh tokens are AES-256-GCM encrypted with a master key stored in your OS keychain (via `keytar`) and persisted to your local SQLite.+OAuth credentials are persisted in the project-scoped `mcp_tokens` table 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. The credentials are not yet encrypted at the application layer, so protect access to `~/.notfair/db.sqlite` and your local user account.## Live transcript@@ -94,7 +97,7 @@ Chat events (deltas, tool calls, lifecycle) are persisted to `transcript_events`## What V1 is and isn't-**Is:** the goal loop — conversational goal intake with server-verified metrics, heartbeat ticks with measurement discipline, per-agent memory, shared workspace context — plus per-agent chat, a native cron scheduler, and an MCP connection hub. Runs on Claude Code or Codex, no proprietary agent runtime.+**Is:** the goal loop — conversational goal intake with server-verified metrics, heartbeat ticks with measurement discipline, per-agent memory, shared workspace context — plus goal chat, PR-governed code changes, and an MCP connection hub. Runs on Claude Code or Codex, no proprietary agent runtime.**Isn't (yet):** cross-goal coordination (resource leases between agents touching the same campaigns), per-LLM-call cost tracking, or a hosted mode. Those land as the loop earns trust in the field.