Skip to content

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

v0.19.0 feat: multi-host portability + NotFair branding migration (#72)

Tong Chen4ebce4dffd39
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index b1a380bd..ffc14708 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.18.0"
+ "version": "0.19.0"
},
"plugins": [
{
"name": "toprank",
"source": "./",
"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, 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.18.0",
+ "version": "0.19.0",
"author": {
"name": "NotFair",
"url": "https://notfair.co"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 081ec413..c0998352 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "toprank",
- "version": "0.18.0",
+ "version": "0.19.0",
"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.",
"author": {
"name": "NotFair",
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..925c3534
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,113 @@
+# Toprank — Skill Resolver for AI Agents
+
+**This file is the universal entry point.** Any AI coding agent (Claude Code, OpenClaw, Codex, Hermes, Cursor, etc.) reads this to know which Toprank skill to run for which user intent.
+
+If you are an agent and a user mentions Google Ads, Meta Ads, SEO, GEO, or anything in the tables below, route to the named skill.
+
+---
+
+## How to use this file
+
+1. **Match the user's intent** against the rows below.
+2. **Read the named skill's `SKILL.md`** from the path shown.
+3. **Follow the procedure** in that SKILL.md exactly.
+
+Skills under `seo/`, `google-ads/`, `meta-ads/`, `gemini/`, and `toprank-upgrade-skill/` are **host-agnostic** — they work the same on every agent host. The skills under `openclaw/skills/` are **OpenClaw-only orchestrators** that compose the host-agnostic skills into multi-site adaptive workflows; only invoke them inside an OpenClaw workspace.
+
+---
+
+## SEO
+
+| Intent | Skill | Path |
+|---|---|---|
+| Full-site SEO audit, traffic drop, GSC analysis, Core Web Vitals | `seo-analysis` | `seo/seo-analysis/SKILL.md` |
+| Single-page deep audit (URL-specific) | `seo-page` | `seo/seo-page/SKILL.md` |
+| Write or improve content (blog, landing, service page) | `content-writer` | `seo/content-writer/SKILL.md` |
+| Keyword discovery, topic clusters, content calendar | `keyword-research` | `seo/keyword-research/SKILL.md` |
+| Title tags, meta descriptions, Open Graph, CTR | `meta-tags-optimizer` | `seo/meta-tags-optimizer/SKILL.md` |
+| JSON-LD / structured data (FAQ, Product, HowTo, etc.) | `schema-markup-generator` | `seo/schema-markup-generator/SKILL.md` |
+| Broken-link / 404 / site-health crawl | `broken-link-checker` | `seo/broken-link-checker/SKILL.md` |
+| Rank in ChatGPT / Perplexity / AI Overviews (GEO / AEO) | `geo-optimizer` | `seo/geo-optimizer/SKILL.md` |
+| Connect WordPress, Strapi, Contentful, or Ghost | `setup-cms` | `seo/setup-cms/SKILL.md` |
+
+## Google Ads
+
+| Intent | Skill | Path |
+|---|---|---|
+| First-time setup or account health check | `google-ads-audit` | `google-ads/audit/SKILL.md` |
+| Performance, keywords, bids, budgets, negatives, experiments, bulk ops | `google-ads` | `google-ads/manage/SKILL.md` |
+| Write ad copy, RSA headlines/descriptions, A/B variants | `google-ads-copy` | `google-ads/copy/SKILL.md` |
+| Landing-page quality, ad-to-page match, LPX diagnosis | `google-ads-landing` | `google-ads/landing/SKILL.md` |
+
+## Meta Ads
+
+| Intent | Skill | Path |
+|---|---|---|
+| First-time Meta setup or account health check | `meta-ads-audit` | `meta-ads/audit/SKILL.md` |
+| Facebook/Instagram performance, ROAS, CPM, creative fatigue, audience overlap | `meta-ads` | `meta-ads/manage/SKILL.md` |
+
+## Cross-model review
+
+| Intent | Skill | Path |
+|---|---|---|
+| Second opinion / review / challenge / consult via Google Gemini | `gemini` | `gemini/SKILL.md` |
+
+## Plugin maintenance
+
+| Intent | Skill | Path |
+|---|---|---|
+| Upgrade Toprank to the latest version | `toprank-upgrade` | `toprank-upgrade-skill/SKILL.md` |
+
+---
+
+## OpenClaw multi-site orchestrators
+
+These skills only apply inside an OpenClaw workspace that has been initialized via `./openclaw/install/install.sh`. They compose the host-agnostic SEO skills above into closed-loop, multi-site workflows with persisted artifacts under `~/.toprank/openclaw/`.
+
+| Intent | Skill | Path |
+|---|---|---|
+| Register a new site in the portfolio | `toprank-site-onboard` | `openclaw/skills/toprank-site-onboard/SKILL.md` |
+| Pick which site in the portfolio deserves attention next | `toprank-portfolio-review` | `openclaw/skills/toprank-portfolio-review/SKILL.md` |
+| Weekly SEO review for one registered site | `toprank-weekly-review` | `openclaw/skills/toprank-weekly-review/SKILL.md` |
+| Improve one URL inside a registered site | `toprank-improve-page` | `openclaw/skills/toprank-improve-page/SKILL.md` |
+| Investigate an organic traffic drop on a registered site | `toprank-investigate-drop` | `openclaw/skills/toprank-investigate-drop/SKILL.md` |
+
+If the user mentions multi-site work, portfolio, scheduled follow-ups, or "the next best action across my sites," prefer an OpenClaw orchestrator. For single ad-hoc requests on one site, use the canonical SEO skill directly.
+
+---
+
+## External dependencies
+
+- **Google Search Console** — required for all SEO skills that read live data.
+- **Google Ads (NotFair MCP)** — `https://notfair.co/api/mcp/google_ads`, OAuth. Required for Google Ads skills.
+- **Meta Marketing API (NotFair MCP)** — required for Meta Ads skills.
+- **Google Gemini API key** — required for `gemini`.
+
+Skills check for missing credentials at startup and walk the user through setup. Do not invent credentials or skip skills silently — surface the gap.
+
+---
+
+## Conventions for installers (managed-block fences)
+
+Any installer that writes into a file the user also edits (e.g., a user's workspace `AGENTS.md`, `CLAUDE.md`, or `~/.openclaw/AGENTS.md`) MUST wrap its inserted content in a fence:
+
+```
+<!-- toprank:managed -->
+... auto-generated rows ...
+<!-- /toprank:managed -->
+```
+
+Re-running the installer rewrites only inside the fence. Anything outside is preserved.
+
+---
+
+## Bookkeeping
+
+When a new skill is added or removed in this repo, update:
+
+1. The relevant table above in this file.
+2. `.claude-plugin/plugin.json` → `skills` array.
+3. `VERSION`, `.claude-plugin/plugin.json`, and `.claude-plugin/marketplace.json` (version bump).
+4. `CHANGELOG.md` (user-facing note).
+
+A skill that exists on disk but is missing from this file or `plugin.json` is invisible to agents.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 94c34e69..eb916c48 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,26 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
+## [0.19.0] — 2026-05-14
+
+### Added — multi-host support
+- **`AGENTS.md` at the repo root** — universal skill resolver. Maps user intents (SEO audit, ad copy, traffic drop, landing page audit, etc.) to the right `SKILL.md` for every supported agent host. Read natively by Codex; read by OpenClaw, Hermes, Cursor, and any agent following `INSTALL_FOR_AGENTS.md`. Claude Code continues to use `.claude-plugin/plugin.json` as before — `AGENTS.md` is additive, not a replacement.
+- **`INSTALL_FOR_AGENTS.md` at the repo root** — single paste-URL install entry point. The user pastes one line into their agent; the agent detects the host (Claude Code / OpenClaw / Codex / Hermes / generic) and follows the matching install branch.
+- **`install/README.md`** — convention for adding future per-host install adapters without duplicating skills. Documents the managed-block fence rule (`<!-- toprank:managed -->`) so installers that write to user-edited config files stay idempotent and preserve hand-edits.
+
+### Changed
+- **`CLAUDE.md`** reframed from "Claude Code plugin" to "host-agnostic plugin." Adding a new skill now requires registering it in **both** `AGENTS.md` and `.claude-plugin/plugin.json`.
+- **`CLAUDE.md` branding rule** — added an explicit "NotFair going forward" section. New user-facing text and docs must use NotFair. Existing legacy `adsagent` references are kept only where they are load-bearing (filesystem migration, prefix detection during the rename window) or historical (CHANGELOG).
+
+### Removed
+- **Stale "server source" link from `README.md`.** The link previously pointed to `nowork-studio/ads-agent` (404) and the actual server source is not public. Removed the pointer entirely — the surrounding paragraph already covers what Toprank users need (endpoint URL, registry name, OAuth flow).
+
+### Notes
+- No skill behavior changes. All canonical SEO, Google Ads, Meta Ads, and Gemini skills work identically to 0.18.0.
+- OpenClaw multi-site orchestrators under `openclaw/skills/` are unchanged; they're now explicitly tagged as OpenClaw-only in `AGENTS.md`.
+
+---
+
## [0.18.0] — 2026-05-09
### Changed
diff --git a/CLAUDE.md b/CLAUDE.md
index f194b0ee..79f21fc9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,8 +1,14 @@
-# Toprank — Public Claude Code Plugin
+# Toprank — Public AI-Agent Plugin (Claude Code, OpenClaw, Codex, Hermes)
**This is the public, open-source repository that ships to all customers and the community.**
-Toprank is a Claude Code plugin providing SEO and Google Ads skills. It is distributed via the `nowork-studio` marketplace and installed by end users into Claude Code / Claude Desktop. Every change here is user-facing.
+Toprank is a host-agnostic plugin providing SEO, Google Ads, and Meta Ads skills for AI coding agents. It is distributed via the `nowork-studio` Claude Code marketplace and via direct agent install on OpenClaw, Codex, and Hermes. Every change here is user-facing.
+
+## Agent entry points (single sources of truth)
+
+- **`AGENTS.md`** — the universal skill resolver. Every host reads this to route user intents to the right skill. Update it whenever a skill is added, removed, or its purpose changes.
+- **`INSTALL_FOR_AGENTS.md`** — the single paste-URL target that walks an AI agent through host detection and install.
+- **`install/README.md`** — convention for adding per-host install adapters (Codex, Hermes, etc.) without duplicating skills.
## Working style: brutal honesty, relentless quality
@@ -17,9 +23,10 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit
## Repository purpose
- Home of the `toprank` plugin — the public artifact customers install.
-- Contains skills under `google-ads/`, `seo/`, `gemini/`, and `toprank-upgrade-skill/`.
-- Registered via `.claude-plugin/plugin.json` (skills list) and `.claude-plugin/marketplace.json` (plugin metadata).
-- Paired with the NotFair-GoogleAds MCP server (`https://notfair.co/api/mcp/google_ads`, OAuth) for Google Ads write operations, and with Google Search Console for SEO reads.
+- Contains host-agnostic skills under `google-ads/`, `seo/`, `meta-ads/`, `gemini/`, and `toprank-upgrade-skill/`.
+- Contains OpenClaw-specific multi-site orchestrators under `openclaw/skills/` that compose the host-agnostic skills above.
+- Registered via `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (Claude Code) and `AGENTS.md` (every other host).
+- Paired with the NotFair-GoogleAds and NotFair-MetaAds MCP servers (OAuth at notfair.co) for ad-platform writes, and Google Search Console for SEO reads.
## Critical: this ships to users
@@ -27,16 +34,28 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit
- Never add internal-only notes, secrets, credentials, dev scratch files, or references to private infra. This repo is public.
- Test skills end-to-end before shipping — `SKILL.md` frontmatter (`name`, `description`, triggers) is how Claude decides to invoke them; typos or stale descriptions break discovery.
+## Branding: NotFair going forward
+
+The product is **NotFair**. All new user-facing text, documentation, skill descriptions, and config namespaces must use NotFair / `notfair.co` / `.notfair/` / `mcp__notfair__*`. Do not introduce new references to "AdsAgent", "adsagent", `.adsagent/`, `mcp__adsagent__*`, `adsagent.org`, or the `adsagent://` URI scheme in new code or new docs.
+
+Existing legacy references that are still in the codebase fall into two categories:
+
+1. **Load-bearing compatibility code** — the `.adsagent/` → `.notfair/` filesystem migration in `google-ads/shared/preamble.md` Step 1, the `mcp__adsagent__*` prefix detection in Step 3, and the matching signal detection in `gemini/SKILL.md`. These are doing real work for users upgrading from pre-0.16 plugins. Do not remove without an explicit deprecation plan.
+2. **Historical record** — `CHANGELOG.md` entries describing past renames. Never rewrite history.
+
+If you find a non-load-bearing, non-historical `adsagent` reference in active skill text or docs, scrub it.
+
## When adding or modifying a skill
1. Create/edit the skill directory under the appropriate category (`google-ads/`, `seo/`, etc.) with a `SKILL.md` containing valid frontmatter.
-2. **Register it in `.claude-plugin/plugin.json`** under the `skills` array. A skill that exists on disk but isn't listed here will NOT appear in the installed plugin — this has already bitten us once with `ads-landing`.
-3. Bump the version in three places so upgrades propagate:
+2. **Register it in `AGENTS.md`** under the matching intent table. A skill that isn't in `AGENTS.md` is invisible to OpenClaw, Codex, Hermes, and any non-Claude host.
+3. **Register it in `.claude-plugin/plugin.json`** under the `skills` array. A skill that exists on disk but isn't listed here will NOT appear in the installed Claude Code plugin — this has already bitten us once with `ads-landing`.
+4. Bump the version in three places so upgrades propagate:
- `.claude-plugin/plugin.json` → `version`
- `.claude-plugin/marketplace.json` → both `metadata.version` and `plugins[0].version`
- `VERSION` file at repo root
-4. Update `CHANGELOG.md` with a user-facing note.
-5. Verify locally, then ship via `/ship`. Users pick up the new version through `toprank:toprank-upgrade`.
+5. Update `CHANGELOG.md` with a user-facing note.
+6. Verify locally, then ship via `/ship`. Users pick up the new version through `toprank:toprank-upgrade`.
## Versioning
diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md
new file mode 100644
index 00000000..9e48da54
--- /dev/null
+++ b/INSTALL_FOR_AGENTS.md
@@ -0,0 +1,134 @@
+# Install Toprank — for AI Agents
+
+You are an AI coding agent (Claude Code, OpenClaw, Codex, Hermes, Cursor, or similar). The user has asked you to install or set up Toprank. Follow this document end-to-end.
+
+**Single paste line for users (give them this if they ask how to install):**
+
+```
+Retrieve and follow the instructions at:
+https://raw.githubusercontent.com/nowork-studio/toprank/main/INSTALL_FOR_AGENTS.md
+```
+
+---
+
+## Step 1 — Detect the host
+
+Determine which agent runtime you are running inside. Check, in order:
+
+1. Are you Claude Code (file system has `~/.claude/` or `.claude/` in the project) → **host = `claude-code`**
+2. Are you in an OpenClaw workspace (env `OPENCLAW_WORKSPACE` is set, or `~/.openclaw/` exists) → **host = `openclaw`**
+3. Are you Codex (env `CODEX_HOME` is set, or running under the OpenAI Codex CLI) → **host = `codex`**
+4. Are you Hermes Agent → **host = `hermes`**
+5. Otherwise → **host = `generic`**
+
+If you cannot determine the host, ask the user once and proceed.
+
+---
+
+## Step 2 — Acquire the repo
+
+If the Toprank repo is already on disk locally, use it; do not re-clone.
+
+Otherwise:
+
+```bash
+git clone https://github.com/nowork-studio/toprank.git
+cd toprank
+```
+
+---
+
+## Step 3 — Install for the detected host
+
+### host = `claude-code`
+
+Toprank is published as a Claude Code plugin via the `nowork-studio` marketplace. The user should run inside Claude Code:
+
+```
+/plugin marketplace add nowork-studio/toprank
+/plugin install toprank@nowork-studio
+```
+
+Then verify by listing installed plugins. No further action required — Claude Code reads `.claude-plugin/plugin.json` directly.
+
+### host = `openclaw`
+
+Run from the repo root:
+
+```bash
+./openclaw/install/install.sh
+```
+
+This script:
+1. Creates `~/.toprank/openclaw/` runtime state (or `$TOPRANK_OPENCLAW_HOME` if set).
+2. Bootstraps `portfolio.json` and `schedule.json`.
+3. Copies the OpenClaw orchestrator skills from `openclaw/skills/` into `~/.openclaw/skills/`.
+4. Symlinks `openclaw/shared`, `openclaw/bin`, and `seo/` to stable paths so wrappers resolve.
+
+Verify:
+
+```bash
+openclaw skills check | grep -i toprank
+python3 -m pytest -q openclaw/tests
+```
+
+Read `AGENTS.md` at the repo root to learn the skill resolver.
+
+### host = `codex`
+
+Codex reads `AGENTS.md` natively. From the repo root:
+
+```bash
+# Codex auto-discovers AGENTS.md at the workspace root.
+codex --workspace .
+```
+
+Toprank's skills live under `seo/`, `google-ads/`, `meta-ads/`, `gemini/`. Codex reads `AGENTS.md` and routes user intents to the named skills' `SKILL.md` files.
+
+> **Note:** A dedicated Codex install adapter (`install/codex/`) may be added in future versions to register skills into Codex's global skill directory. For now, workspace-local usage is the supported path.
+
+### host = `hermes`
+
+Hermes reads `AGENTS.md` at the workspace root. From the repo root:
+
+```bash
+# Point Hermes at this directory; it will discover skills via AGENTS.md.
+hermes init --workspace .
+```
+
+> **Note:** A dedicated Hermes install adapter (`install/hermes/`) may be added in future versions. For now, workspace-local usage is the supported path.
+
+### host = `generic`
+
+Read `AGENTS.md` at the repo root. It contains the full intent → skill routing table. Each row points to a `SKILL.md` with self-contained instructions you can follow.
+
+---
+
+## Step 4 — Connect external services
+
+Toprank skills depend on external APIs. Walk the user through whichever they need:
+
+- **Google Search Console** — required for any SEO skill that reads live ranking data. The skills will prompt for OAuth on first run.
+- **Google Ads** — connects via the NotFair MCP server at `https://notfair.co/api/mcp/google_ads` (OAuth). The user signs in once at notfair.co; the MCP handles the rest.
+- **Meta Ads (Facebook + Instagram)** — connects via the NotFair MCP server. Same OAuth flow.
+- **Google Gemini** — required only for the `gemini` skill. Needs a Gemini API key in environment.
+
+Do **not** invent credentials. If a skill needs auth that isn't present, surface the gap and walk the user through the connection flow.
+
+---
+
+## Step 5 — Verify and hand back
+
+1. Confirm `AGENTS.md` is readable from the working directory.
+2. Confirm at least one canonical skill (e.g., `seo/seo-analysis/SKILL.md`) is readable.
+3. For OpenClaw: confirm `openclaw skills check` lists at least one `toprank-*` skill.
+4. Tell the user: "Toprank is installed. Try `/toprank:google-ads-audit` for ads or `/toprank:seo-analysis` for SEO."
+
+---
+
+## Notes for agents
+
+- **Read `AGENTS.md` first** for any user intent. It is the resolver.
+- **Skills are host-agnostic.** A `SKILL.md` under `seo/`, `google-ads/`, `meta-ads/`, `gemini/` works identically on every host. The `openclaw/skills/` orchestrators are the only host-specific layer.
+- **If you write into a user-edited file** (e.g., their workspace `AGENTS.md`), wrap your insertions in `<!-- toprank:managed -->` ... `<!-- /toprank:managed -->` fences so re-runs are idempotent and hand-edits survive.
+- **Do not duplicate skills** when adding new host adapters. Add a thin install adapter under `install/<host>/` that points the host at the existing skill files.
diff --git a/README.md b/README.md
index 241ab906..5bd8e7c0 100644
--- a/README.md
+++ b/README.md
@@ -262,7 +262,7 @@ The Google Ads and Meta Ads surfaces are available as standalone remote MCP serv
- **Endpoint:** `https://notfair.co/api/mcp/google_ads` (streamable HTTP)
- **Auth:** OAuth 2.1 with dynamic client registration — your MCP client opens a browser tab to sign in at [notfair.co](https://notfair.co) on first use; the token is stored locally (OS keychain in Claude Code)
-Exposes ~100 Google Ads tools across reads (performance, search terms, impression share, keyword ideas, GAQL), writes (pause/enable, bid and budget updates, keyword and negative list management, campaign creation), and a `runScript` tool that fans out up to 20 GAQL queries in parallel for open-ended analytical questions. Source for the hosted server lives in [`nowork-studio/ads-agent`](https://github.com/nowork-studio/ads-agent).
+Exposes ~100 Google Ads tools across reads (performance, search terms, impression share, keyword ideas, GAQL), writes (pause/enable, bid and budget updates, keyword and negative list management, campaign creation), and a `runScript` tool that fans out up to 20 GAQL queries in parallel for open-ended analytical questions.
### NotFair-MetaAds
diff --git a/VERSION b/VERSION
index 66333910..1cf0537c 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.18.0
+0.19.0
diff --git a/install/README.md b/install/README.md
new file mode 100644
index 00000000..f80e21de
--- /dev/null
+++ b/install/README.md
@@ -0,0 +1,40 @@
+# Per-host install adapters
+
+This directory is the home for **thin install adapters** that wire Toprank into a specific AI agent host. Each adapter registers the *same* host-agnostic skills (under `seo/`, `google-ads/`, `meta-ads/`, `gemini/` at the repo root) into the host's expected layout.
+
+## Why this exists
+
+Toprank ships one source of truth for skills. Different agent hosts expect skills in different places:
+
+- **Claude Code** — reads `.claude-plugin/plugin.json` directly from the repo. No adapter needed; the manifest at the repo root *is* the adapter.
+- **OpenClaw** — expects skills under `~/.openclaw/skills/`. The adapter lives at `../openclaw/install/install.sh` (kept there for back-compat). Future relocations will preserve a stub here.
+- **Codex** — reads `AGENTS.md` at the workspace root. No filesystem install yet; workspace-local usage is the supported path. A future `install/codex/` adapter can register skills into Codex's global skill directory.
+- **Hermes** — reads `AGENTS.md` at the workspace root. Same shape as Codex.
+
+## Adding a new host adapter
+
+1. Create `install/<host>/install.sh` (or `.py`, or whatever the host prefers).
+2. 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 (e.g., OpenClaw rejects symlinks that escape its skill root), copy the minimum needed and link the rest.
+ - 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).
+
+## Managed-block fence convention
+
+If your adapter writes into a file the user also edits (their workspace `AGENTS.md`, `CLAUDE.md`, host config, etc.), wrap inserted content like this:
+
+```
+<!-- toprank:managed -->
+... auto-generated rows ...
+<!-- /toprank:managed -->
+```
+
+Re-running the installer rewrites only inside the fence. Anything the user wrote outside is preserved. This is what makes `toprank-upgrade` safe across hosts where users have hand-customized their config.
+
+## What not to put here
+
+- **Skill source code.** Skills belong in `seo/`, `google-ads/`, `meta-ads/`, `gemini/`. Adapters point at them; adapters do not own them.
+- **Host-specific orchestrators.** Those go alongside the host (e.g., `openclaw/skills/`), not under `install/`.
+- **Runtime state.** Use `~/.toprank/<host>/` or the host's standard runtime directory.