<aside> π‘ Use case: decide which searches matter, which page owns each one, and which changes are worth acting on. Everything below your lines is noise and stays in the weekly summary.
</aside>
<aside>
π Who reads this folder: Search visibility and Market radar, plus the orchestrator. The playbooks "Ranking drops a page" and "Search demand spikes" use serp-rules.md to decide whether to fire. Your weekly exports land in this folder too.
</aside>
<aside> πΊοΈ Controls: which keywords you care about and which single page owns each one, so two of your pages never chase the same search.
How to fill it: open your Google Search Console queries export and your Semrush keyword list. Group keywords into clusters, give each cluster one owning page and an intent label. Put keywords you want but have no page for under "Gaps".
Save as brand-os/signals-seo/keyword-map.md.
</aside>
# Keyword map
> Read by: search-visibility, market-radar. The orchestrator copies the keyword into content briefs from here.
> One keyword, one owning page. When two pages chase the same keyword, search-visibility flags it.
> Fill it from your Google Search Console queries export and your Semrush keyword list.
## Intent labels
| Label | Means the searcher wants to |
|---|---|
| learn | understand something (how to, what is, why) |
| compare | weigh options before buying (best, vs, reviews) |
| buy | act now (price, order, near me, book) |
| find us | reach your brand by name |
## Keyword clusters
| Cluster | Intent | Primary keyword | Other keywords in the cluster | Owning page URL | Status |
|---|---|---|---|---|---|
| [FILL IN: topic] | [FILL IN: learn, compare, buy or find us] | [FILL IN] | [FILL IN: comma list] | [FILL IN: URL, or "none yet"] | [FILL IN: owned, gap or planned] |
| [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] |
| [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] |
Example row (Northwind Coffee): | Home brewing | learn | how to brew pour over coffee | pour over ratio, pour over grind size | /guides/pour-over | owned |
## Gaps
Keywords you want and have no page for. Agents may add rows, always with the status `idea`.
| Keyword | Intent | Why it matters | Proposed page | Status | Added by |
|---|---|---|---|---|---|
| [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | idea | [FILL IN: you, or the agent name] |
## Keywords we ignore
Agents skip these even if they spike.
| Keyword | Why we ignore it |
|---|---|
| [FILL IN] | [FILL IN: wrong audience, a product we do not sell, a competitor's brand name] |
Example row (Northwind Coffee): | free coffee samples | brings visitors who do not buy |
<aside> π Controls: what counts as a ranking drop, a demand spike or a competitor move, and how loud each one is.
How to fill it: every number in this file is yours. Until you set one, the agents report the change and take no action on it. Start strict, so only big moves trigger a playbook, and loosen it once you trust the output.
Save as brand-os/signals-seo/serp-rules.md.
</aside>
# SERP rules
> Read by: search-visibility, market-radar, and the playbooks ranking-drops-a-page and search-demand-spikes.
> These rules decide which search changes are worth acting on. Anything under these lines is noise:
> it goes in the weekly summary and nothing else happens.
> Every number below is yours to set. Until you set it, agents report the change and take no action.
## 1. A ranking drop
- Counts when a page falls [FILL IN: how many positions a page can drop before it counts] positions for its primary keyword in keyword-map.md
- Compared with: [FILL IN: last week, or the average of a period you choose]
- Ignore keywords with fewer than [FILL IN: monthly searches below which you do not care] monthly searches
- Ignore pages that are not in keyword-map.md: [FILL IN: yes or no]
- What happens: search-visibility checks the page and the results page, then the orchestrator runs /ranking-drops-a-page
## 2. A demand spike
- Counts when impressions or searches for a query rise by [FILL IN: the rise that counts as a spike] over [FILL IN: the period you compare against]
- Read from: [FILL IN: the Google Search Console impressions export, the Semrush export, or both]
- Only for queries that: [FILL IN: match a cluster in keyword-map.md, or any query]
- What happens: the orchestrator runs /search-demand-spikes
## 3. A competitor move on the results page
- Counts when a competitor from brand-brain/positioning.md enters the top [FILL IN: how many results you watch] for one of your primary keywords
- What happens: market-radar adds it to its weekly report. No content is written unless the orchestrator briefs it.
## 4. Results page features we care about
| Feature | Do we want it | Which pages |
|---|---|---|
| Featured snippet | [FILL IN: yes or no] | [FILL IN] |
| People also ask | [FILL IN] | [FILL IN] |
| Local pack (map results) | [FILL IN] | [FILL IN] |
| Video results | [FILL IN] | [FILL IN] |
| Image results | [FILL IN] | [FILL IN] |
## 5. How loud each change is
| Level | Example | Who hears about it | When |
|---|---|---|---|
| Low | [FILL IN: a small move on a minor keyword] | weekly summary only | weekly |
| Medium | [FILL IN] | the orchestrator briefs a department | next run |
| High | [FILL IN: a top page drops out of view] | an alert to the owner | [FILL IN: right away, or next morning] |
Example row (Northwind Coffee): | High | The pour over guide stops showing for "how to brew pour over coffee" | alert to the owner | next morning |
## 6. Never
- Change a live page without the change passing owner/approval-bar.md.
- Act on one day of data.
<aside> π Controls: where each important page should rank, and by when. Search visibility reports every page that is behind.
How to fill it: list the pages that earn you money first. Set your own target position and date for each. Leave "Latest position" blank: agents fill it from your exports and name the file they read.
Save as brand-os/signals-seo/ranking-targets.md.
</aside>
# Ranking targets
> Read by: search-visibility, market-radar.
> Where each important page should rank, and by when. Search-visibility compares the latest export with this file
> and reports every page that is behind.
> Agents may update only the "Latest position" and "Checked on" columns, and only from an export or a connection.
> They name the file they read in the "Checked from" column.
## Targets
| Page URL | Primary keyword | Target position | Target date | Latest position | Checked on | Checked from | Priority |
|---|---|---|---|---|---|---|---|
| [FILL IN] | [FILL IN: from keyword-map.md] | [FILL IN] | [FILL IN] | | | | [FILL IN: high, medium or low] |
| [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | | | | [FILL IN] |
| [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | | | | [FILL IN] |
Example row (Northwind Coffee): | /guides/pour-over | how to brew pour over coffee | [your target] | [your date] | | | | high |
## Pages that matter most
List the pages where a drop costs you money. A drop on one of these is always at least Medium in serp-rules.md.
1. [FILL IN: URL and why it matters]
2. [FILL IN]
3. [FILL IN]
## When a target date passes and the page is still behind
- [FILL IN: refresh the page, set a new date, or drop the target]
- Who decides: [FILL IN: name]
<aside> π Controls: which export or connection feeds each signal, what the file is called and how often it arrives. The orchestrator uses it to tell fresh data from stale data.
How to fill it: the rows for every tool in the system are already there. Delete the tools you do not use, fill in how often you drop each export and who drops it, and set your freshness rule. When you later connect a tool through its API or an MCP server, record it in the bottom table. Nothing else changes.
Save as brand-os/signals-seo/tracking-setup.md.
</aside>
# Tracking setup
> Read by: search-visibility, market-radar. The orchestrator reads it to know which data is fresh.
> One row per signal: where it comes from, how it gets into this folder, and how often.
> Start every row with a manual export. Switch a row to an API or MCP connection later; nothing else changes.
## Feeds
| Signal | Tool | How it gets in | File name | How often | Who drops it | Used by |
|---|---|---|---|---|---|---|
| Search queries, clicks, positions | Google Search Console | export | gsc-queries-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | search-visibility |
| Sessions and where they came from | Google Analytics 4 | export | ga4-sessions-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | search-visibility, results-roi |
| Rankings, yours and competitors' | Semrush | export | semrush-rankings-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | search-visibility, market-radar |
| Backlinks | Ahrefs | export | ahrefs-backlinks-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | search-visibility |
| Site crawl issues | Screaming Frog | export | crawl-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | search-visibility |
| Reviews | Google Business Profile | export | gbp-reviews-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | reviews-reputation (through the orchestrator) |
| Facebook and Instagram insights | Meta Business Suite | export | meta-insights-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | publishing-social, results-roi |
| Company page analytics | LinkedIn | export | linkedin-page-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | publishing-social, results-roi |
| Channel analytics | YouTube | export | youtube-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | creative-studio, results-roi |
| Web mentions | Brand24 | export | brand24-mentions-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | market-radar, reviews-reputation |
| Audience research | SparkToro | export | sparktoro-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | market-radar |
| Competitor traffic | Similarweb | export | similarweb-YYYY-MM-DD.csv | [FILL IN] | [FILL IN] | market-radar |
| Alerts | Google Alerts | email digest saved as text | google-alerts-YYYY-MM-DD.md | [FILL IN] | [FILL IN] | market-radar |
Delete the rows for tools you do not use. Add a row for any tool you do.
## Freshness
- A file counts as stale when it is older than [FILL IN: how old an export can be before agents stop trusting it]
- A stale file is reported, never acted on: the agent writes "data stale" in its report and takes no action on that signal.
## Moving a row to a connection
| Tool | Connected through | Switched on | Notes |
|---|---|---|---|
| [FILL IN] | [FILL IN: API or MCP server name] | [FILL IN: date] | [FILL IN] |
## Never
- Paste an API key, password or token into this folder. Connections hold their own keys.
<aside> π Next: /content
</aside>