Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

docs(guides): add Content Editor, Mentions, Site Audit and Action Center guides; update Prompts and AI Traffic (#1408)

Gökhan Geyik0711ad18fe1e
diff --git a/docs/guides/action-center.mdx b/docs/guides/action-center.mdx
new file mode 100644
index 000000000..a6d3fb70c
--- /dev/null
+++ b/docs/guides/action-center.mdx
@@ -0,0 +1,208 @@
+---
+title: "Action Center"
+description: "Turn what changed in AI search into a ranked list of work: actions, their tasks and the Priority Score."
+---
+
+## What this module does
+
+The **Action Center** (`/dashboard/action-center`) is where Ansvisor turns signals into prioritized work. It is the first page you see after you sign in, and it has four tabs:
+
+- **Actions** (`/dashboard/action-center/actions`) — what to do now, ranked by Priority Score
+- **Signals** (`/dashboard/action-center/signals`) — what changed across your AI visibility data
+- **KPIs** (`/dashboard/action-center/kpis`) — the goals you track for the brand
+- **History** (`/dashboard/action-center/history`) — what was done, and what it moved
+
+Everything is per brand: switch brands to see another brand's actions. While a new brand's first analysis runs, a **First analysis running** note sits under the tabs; actions, signals and KPIs fill in once it finishes.
+
+## Getting started
+
+A new brand starts with **Getting started**: a fixed list of 17 steps on the Actions tab. While it runs, the **Getting started** category opens first and lists the steps in a table with their **Stage**, **Status** and **Ready** time, and a **Getting started** card shows how many are done. Click **All** or another category to see your actions.
+
+The steps unlock when their data is ready, not on a schedule:
+
+| Stage | Steps | Ready |
+|---|---|---|
+| **Set up** | Set your KPIs · Add at least 3 competitors · Add at least 3 topics · Add 3 prompts per topic · Connect Google Search Console · Connect Google Analytics · Add the AI Traffic snippet | Now |
+| **Explore** | See where you stand in Visibility · Read your first AI answers · Track high-value prompt suggestions · Check what AI says about you · See who AI quotes · See visits from AI | When the first AI answers are in (about 3 hours). The high-value prompts step waits about 24 hours after you connect Search Console or Analytics. |
+| **Act** | Pick content from suggestions · Create your first content · Optimize a page | When the first content suggestions are in (about 24 hours) |
+| **Ready** | You're ready | After every step above is done or skipped |
+
+Click a step to open its card: why it matters, how to do it, and when it counts as done. The card's button opens the step's page in a new tab. Most steps are checked automatically from your data (three competitors saved, a first AI visit detected, a draft marked ready), so the step updates when you come back to the Action Center tab. A step still waiting for its data says when it opens.
+
+**Connect Google Search Console** and **Connect Google Analytics** are optional. Admins and managers can **Skip** them; a skipped step counts as complete, and you can still connect later from Settings. Without either one, prompt and content suggestions are less accurate.
+
+### Start and skip
+
+Admins and managers see **Get Started** or **Skip Get Started** at the top right of the Actions tab:
+
+- **Skip Get Started** puts the actions list back to normal. Steps you finished stay done, and you can start again any time from the same button.
+- **Get Started** appears after a skip, and for an existing brand whose setup looks incomplete: fewer than 3 competitors or topics, no Search Console, or no content in the last 30 days.
+- A brand added to an organization that already has one asks first: **Run Getting started for [brand]?** Choose **Run Getting started** or **Skip**.
+
+Getting started's steps are not actions: they have no Priority Score and never go through the signal engine.
+
+## Actions
+
+An **action** is one piece of work with an outcome, built from the evidence behind it. Ansvisor consolidates many signals into one action: six valuable pages with no AI traffic become one "Capture AI traffic" action with six linked signals, not six rows. Actions are generated after the daily tracking run, at most five new ones per brand per day, so the list stays short enough to act on.
+
+Each action belongs to a category:
+
+| Category | What it is for |
+|---|---|
+| **Growth** | Ground you could win: demand, topics, platforms or pages where you could appear more |
+| **Protect** | Ground you hold that is starting to slip |
+| **Recover** | Ground you held and lost: visibility, citations, mentions or traffic |
+| **Fix** | Issues on your own site, such as low audit scores, blocked crawlers or broken links AI sends people to |
+| **Compete** | Places where competitors lead you |
+
+### The Actions tab
+
+The cards at the top count and filter the list. Click one to narrow the table to exactly what it counts, and click it again to clear it:
+
+- **Top Actions** — the five highest-priority open actions
+- **At Risk** — open Recover and Fix actions
+- **Opportunities** — open Growth actions
+- **In Progress** — actions someone is working on
+- **Highest Priority** — the highest level among open actions
+
+Below them, filter by category, **Priority**, **Status** and **Assignee**, or search. **Sort** by Priority (the default), Newest, Due date or Recently updated. Filters live in the URL, so a filtered view can be shared.
+
+An action's status is **New**, **In Progress**, **On Hold**, **Completed** or **Dismissed**. The row menu sets In Progress, Completed or Dismiss without opening the action. **Delete** (admins and managers only) removes it for everyone, and it won't come back on its own the next day.
+
+### Inside an action
+
+Click a row to open the action. Under its title you set **Status**, **Assignee** and **Due date**. The tabs are:
+
+- **Overview** — *Why this priority?*, *Why this action?* with the signals that support it, the **Goal** (what done looks like, with a date), and the **KPIs** it is linked to. An action sent from another page also shows where it came from.
+- **Affected** — the prompts, pages, topics, competitors or platforms it is about, with each prompt's demand.
+- **Tasks** — the work, step by step (see below).
+- **Signals** — the evidence behind it. Click one to open it on the Signals tab.
+- **History** — every change: created, new signals linked, status and assignee changes, tasks updated or sent.
+
+### Tasks
+
+Each action comes with tasks: concrete steps such as "Refresh content for these prompts" or "Add structured data to these pages". Open a task to see its details: **What**, **Where**, **Why**, **How** (one step per line), **Done when**, **Type** (Content, On-page, Technical, Outreach, PR or Product), **Effort** and **Role**. Click **Edit** to change any of them.
+
+A task's status is **To Do**, **In Progress**, **Completed** or **Skipped** (with a reason). Skipped tasks leave the count, so they don't hold an action short of done. Use **Add task** for work of your own, and delete tasks you don't need.
+
+From a task you can also:
+
+- **Create content** or **Optimize page** — open a draft in the [Content Editor](/guides/content-editor) for this task. **Open draft** returns to it, and marking the draft ready completes the task.
+- **Send to Content** — send a content task to Content as an opportunity, where a brief can be written for it.
+- **Send to webhook** — post the task to the brand's webhook, for a workflow outside Ansvisor. The webhook is set up under **Content → Webhook Settings**, with the **Action Center task sent** event selected.
+
+Where AI task writing is on for your workspace, **Regenerate tasks** writes the action's tasks again from its evidence. Done, under-way and hand-added tasks stay. It uses your plan's monthly AI allowance.
+
+Some tasks that only read data, such as checking a page's traffic in your connected Analytics, can be carried out by Ansvisor itself overnight. The action's History says so. Nothing that would change something outside Ansvisor runs without your approval: such a task waits as **Waiting Approval**.
+
+### Assigning work
+
+An action with no one on it belongs to **Everyone** in the workspace until someone takes it. Pick a teammate in the action's **Assignee** field, and set a **Due date** if it has one. The **Assignee** filter on the Actions tab shows one person's actions, or **Everyone** for the unassigned ones.
+
+### Export
+
+- **Export CSV** on the Actions tab downloads the actions in the current view, as filtered, with their priority, status, assignee, due date, task progress and affected items.
+- Inside an action, **Copy Data** opens the whole action as Markdown to paste into a doc or ticket, and **Export** downloads it as **Export CSV** or **Export Excel**. The Excel file has one sheet each for the action, its affected items, tasks, signals and history.
+
+## The Priority Score
+
+Every action has a **Priority Score** from 0 to 100: how soon to work on it beside the others. Impact says how much an action could matter; priority weighs impact together with the evidence behind it. The score sets the default order of the Actions tab and the Top Actions card.
+
+| Level | Score |
+|---|---|
+| **Critical** | 90 and above |
+| **High** | 75–89 |
+| **Medium** | 50–74 |
+| **Low** | Below 50 |
+
+### What goes into it
+
+The score weighs seven things:
+
+- **Impact** — the action's impact grade: high, medium or low.
+- **Demand** — how much the prompts, search queries or pages it is about are searched or visited. Only the most demanded few count, so a long list of low-demand prompts doesn't outrank a handful that people actually search for.
+- **Severity** — what kind of change it is. A loss ranks above a sharp drop, a drop above a slip, and a slip above a gap or a site issue. Room to grow and gains rank lowest.
+- **Business value** — how commercial the searches are, or what a page is worth to the business (revenue, transactions or key events, from Google Analytics).
+- **Confidence** — how many independent kinds of finding and data sources agree. Ten signals repeating one finding count as one.
+- **Recoverability** — ground you held and lost is nearer at hand than ground you never held. Fixes on your own site count as within reach too.
+- **Recency** — newer evidence counts more. Its weight halves roughly every ten days.
+
+Demand or business value that nothing measures counts as neutral: it neither raises nor lowers the score.
+
+An action sent from another page has no detection signals, so it is scored from what it carries: the prompt's platforms for an Improve action, the prompts of a content opportunity or draft, the pages sent from AI Traffic.
+
+### When it changes
+
+An action is scored when it is created, and again every night from that night's evidence: its open signals, how recent they are, and the demand behind them. When you resolve or dismiss a signal, the actions it supports are scored again right away. An action not scored yet shows a dash and sorts after the scored ones.
+
+### Why this priority?
+
+The action's **Overview** tab starts with **Why this priority?**: one sentence written from the facts the score rests on. It says what changed, on what, how recently, and what makes it matter, for example:
+
+> Lost ground on 7 high-demand prompts 2 days ago — commercial intent, previously visible, confirmed by 2 sources.
+
+<Note>
+The Content Plan has its own Priority Score, which ranks the Plan's pages. The two are worked out separately. See [Content Editor](/guides/content-editor).
+</Note>
+
+## Signals
+
+The **Signals** tab lists what changed: a visibility drop, a lost citation, a competitor gaining, a page with no AI traffic, a site issue. Signals are detected after your daily tracking runs, and they are the evidence actions are built from.
+
+- **Cards** — Total, Important (high impact), New and Resolved signals, and the average signal impact, for the selected range (7, 30 or 90 days) against the range before.
+- **Filters** — by category (Visibility, Citation, Mention, Traffic, Technical, Competitor), **Impact**, **Status**, **Source** (AI Results, Google Analytics, Google Search Console, Site Audit) and **Platform**, plus search.
+- **Status** — **New**, **Acknowledged**, **Resolved** or **Dismissed**. The row menu sets them, and **Reopen** brings one back.
+
+Click a signal to see **Where** it was found, **What changed** (before and after, with the periods compared), **Evidence and links**, **Related KPIs**, and **Used by actions**. Copies of one finding (the same prompt text tracked as several prompts) are grouped into one row and counted once.
+
+Many of the same changes also appear in the [Daily Pulse](/guides/daily-pulse) email.
+
+## KPIs
+
+The **KPIs** tab tracks the goals you set for the brand. Each KPI shows its **Value**, **Change**, **Trend (7D)**, **Goal**, progress **vs Goal**, and a **Status**:
+
+| Status | When |
+|---|---|
+| **Goal Reached** | 100% of the goal or more |
+| **On Track** | 70% or more, and not moving the wrong way |
+| **At Risk** | 40–69%, or moving the wrong way before the goal is reached |
+| **Off Track** | Under 40% |
+
+The KPIs you can track are AI Visibility, Citations, Mentions, Share of Voice, AI Referral Traffic, Positive Sentiment and Lead over top competitor. A brand that never had KPIs starts with a suggested set, each aiming 20% above its last 30 days. It is saved the first time an admin or manager opens the tab.
+
+**Edit KPIs** (or **Configure KPIs**) opens the framework: pick a template (**AI Search Visibility**, **Brand Monitoring** or **Custom Framework**), a time period (Weekly, Monthly or Quarterly), and a target for each KPI, then **Save & Apply**. Only admins and managers can change KPIs. An action's Overview lists the KPIs it is linked to.
+
+## History
+
+The **History** tab lists actions once they are In Progress, On Hold, Completed or Dismissed, with what they were meant to do and what has been measured since. Filter by range (7d, 30d, 90d, All), **Status**, **Type**, **Priority** and **Source**, and sort by Newest, Oldest or Priority. The cards count total, completed, in-progress, no-improvement and dismissed actions in the window.
+
+Click an action to see **What was the goal?**, **What happened?** (the signals it was built from), its affected items and tasks, and the **Result**:
+
+- When a completed action's week after closing is over, Ansvisor compares its metrics over the 7 days before it was raised with the 7 days after it closed. The result reads **Improved**, **No meaningful change** or **Declined**. It is measured after the action, not proven to be caused by it.
+- A dismissed action is **Not measurable**, and so is one with no metric to read.
+- An action sent from a prompt's Improve tab reports on how many platforms its position improved. It is read again daily while the action is open and for 30 days after it is completed.
+
+When an action is closed, its condition can open a new action after a two-week rest if it is still firing. The old one stays in History as the record of that round of work.
+
+## Where actions come from
+
+Most actions are generated from signals each night. You can also send work to the Action Center from other pages. A sent action has no detection signals; its evidence is what you sent, shown on its Overview tab.
+
+| From | How |
+|---|---|
+| **Mentions** | Select answers on the Mentions tab, or open one, and click **Send to Action Center**. |
+| **Content** | **Send to Actions** on a content opportunity; **Assign to…** on a Content Plan row; or **Who does it → Team** when you start new content. See [Content Editor](/guides/content-editor). |
+| **Site Audit** | Audit results become signals with the Site Audit source, such as low AEO scores or missing structured data, and turn into Fix actions overnight. |
+| **AI Traffic** | On the [AI Traffic Analytics](/guides/ai-traffic-analytics) pages list, select pages under *Cited, not clicked* or *No AI traffic* and click **Send to Action Center**. Traffic drops and strong or weak landing pages also arrive as signals. |
+| **Insights** | **Send action** on a topic in Insights' Opportunities opens a Growth action for it. |
+| **Prompts** | **Send Actions** on a prompt's Improve tab sends the selected suggestions as one action. |
+
+Sending the same thing twice doesn't create a second action: the page says it is already in the Action Center, with its action number (for example `AC-42`).
+
+<Tip>
+Work from the **Top Actions** card each week. Assign each action, set a due date, and close it as **Completed** when its tasks are done, so History can measure the result.
+</Tip>
+
+<Card title="Continue: Answer Engine Insights" icon="arrow-right" href="/guides/answer-engine-insights">
+ See where your brand stands across AI engines.
+</Card>
diff --git a/docs/guides/ai-traffic-analytics.mdx b/docs/guides/ai-traffic-analytics.mdx
index c46216786..82770d10c 100644
--- a/docs/guides/ai-traffic-analytics.mdx
+++ b/docs/guides/ai-traffic-analytics.mdx
@@ -1,52 +1,205 @@
---
title: "AI Traffic Analytics"
-description: "Measure real visits to your site from AI answer engines."
+description: "Measure real visits to your site from AI answer engines, what they're worth, and which AI bots read your pages."
---
## Why this exists
-Most analytics platforms (Google Analytics, Plausible, etc.) lump AI traffic into "direct" or "referral" buckets — they can't tell you a visitor arrived from ChatGPT vs. perplexity.ai. Ansvisor's tracking pixel reads the referrer chain, classifies AI sources by domain, and gives you a clean breakdown.
+Most analytics platforms (Google Analytics, Plausible, etc.) lump AI traffic into "direct" or "referral" buckets — they can't tell you a visitor arrived from ChatGPT vs. perplexity.ai. Ansvisor's tracking snippet reads the referrer, classifies AI sources by domain, and gives you a clean breakdown. Connect Google Analytics, Google Search Console and your Cloudflare or Vercel, and the same page shows what those visits are worth, whether AI is changing your Google traffic, and which AI bots read your pages.
+
+## Data sources
+
+The **AI Traffic Analytics** page (`/dashboard/traffic`, **AI Referral Traffic** in the sidebar) reads up to four sources. The **Data sources** strip at the top shows each one's state:
+
+| Source | What it adds |
+|---|---|
+| **Tracking snippet** | AI-referred visits, page by page, as they happen. Reads **Active · last visit …** once it has sent a visit in the last week, otherwise **Not detected**. |
+| **Google Analytics** | AI visits on days the snippet has none, plus engaged visits, key events, revenue and the AI share of all traffic. |
+| **Google Search Console** | Google clicks, the pages where AI may be taking them, and the Google queries you don't track yet. |
+| **AI bots** | Which AI bots read your pages, from your own Cloudflare or Vercel. Growth plan and above. |
+
+A section whose source isn't connected stays on the page with a **Needs …** tag and a **Connect** button, rather than hiding. Only admins and managers can connect a source.
## Setup
<Steps>
- <Step title="Get the snippet">
- On the **AI Traffic Analytics** page (`/dashboard/traffic`), copy the snippet at the top. It looks like:
+ <Step title="Add the tracking snippet">
+ Copy the snippet from the page. It sits at the top until the snippet has sent a visit in the last week; after that, **Code** in the Data sources strip opens it. It looks like:
```html
- <script src="https://api.ansvisor.com/t.js" data-t="YOUR_TRACKING_CODE" defer></script>
+ <script src="https://YOUR_API_URL/t.js" data-t="YOUR_TRACKING_CODE" defer></script>
```
+ The page fills in your own address and tracking code, so copy it rather than typing it.
</Step>
<Step title="Paste into your site">
- Add the script before `</head>` on every page you want to track. For Next.js, drop it in your root layout. For Wordpress, use a header injection plugin. For static sites, edit the template.
+ Add the script before `</head>` on every page you want to track, **your 404 page included**, so [Broken AI links](#pages) can see visitors who land on a missing page. For Next.js, drop it in your root layout. For WordPress, use a header injection plugin. For static sites, edit the template.
+ </Step>
+ <Step title="Connect Google Analytics and Search Console (optional)">
+ Click **Connect** on either card in the Data sources strip and sign in to Google; access is read-only. If the card then reads **Connected · choose a property for this brand**, pick the property under **Manage** (Settings → Integrations). Connections are shared across your organization.
+
+ Google Analytics' first numbers arrive in about 15 minutes; up to 14 months of history can take up to 24 hours. Search Console's can take up to 48 hours, because Google reports about two days late. On a self-hosted server, both read **Not set up on this server** until the server has its Google connection keys.
</Step>
<Step title="Wait for first visits">
- Visits start appearing immediately. The dashboard updates in near-realtime (≤1 minute).
+ A visit is stored as soon as an AI-referred visitor lands. Reload the page, or change the range, to see new ones.
</Step>
</Steps>
+## Date range, changes and export
+
+- **Range** — 24h, 7d, 30d, 90d, All or Custom. The page opens on the last 24 hours, then on the range you last picked in this browser. Every section follows it.
+- **Change** — each figure is compared with the period of the same length just before. Below 30 visits in either period the change reads **Low sample** instead of a percentage, and a platform or page with no visits before reads **new**. All time has no previous period.
+- **Export** — the **Export** button gives the whole page as **Excel (.xlsx)**, one sheet per section, or **CSV (.zip)**, one CSV per section. Each table also has its own Excel and CSV buttons. A range with more than 100,000 visits is too large to export at once.
+
+## How visits are counted
+
+- **One visit per session.** A reload, or a further link from the same answer, continues the visit rather than counting another. The visits card gives the pageviews beside the visits.
+- **Snippet or Google Analytics, never both.** On days the snippet sent any visit, the page counts the snippet's; on the other days, Google Analytics'. The two are never added together, and the visits card says how many days came from Google Analytics.
+- **The visit list is the snippet's.** Google Analytics doesn't report single visits, so the **Recent AI Referral Visits** list shows only what the snippet saw.
+
## What you see
+The sections run top to bottom in this order.
+
+### Summary line
+
+One or two sentences above the KPI cards, for example: *"Last 7 days: 120 AI-referred visits, 3.2% of all traffic, up 18% on the previous period. ChatGPT sent the most (64), and its visitors convert best (6% of their visits had a key event). 4 pages are cited in AI answers but get no clicks. 12 Google queries with clicks aren't tracked as prompts."*
+
+Each fact appears only when the page can back it: the change needs 30 visits in both periods; the share of traffic and the best-converting platform need Google Analytics (and two platforms with 30 visits and 5 key events each); the untracked queries need Search Console.
+
+### KPI cards
+
+| Card | What it shows | Needs |
+|---|---|---|
+| **AI-referred visits** | Visits from AI assistants, with the change on the previous period | Snippet or Google Analytics |
+| **Top platform** | The AI platform that sent the most visits | — |
+| **Platforms** | How many AI platforms sent at least one visit | — |
+| **AI share of traffic** | AI-referred visits as a share of all the sessions Google Analytics recorded | Google Analytics |
+| **Engaged visits** | The share of AI sessions Google Analytics counts as engaged, beside the same share for Google organic | Google Analytics |
+| **Key events from AI** | Key events (conversions) in AI sessions, their rate against Google organic, and revenue when the property reports purchases | Google Analytics |
+| **Google clicks** | Clicks from Google Search. Google reports about two days late, so 24h and 7d show its latest reported days | Search Console |
+
+### Trend and platforms
+
<CardGroup cols={2}>
- <Card title="KPI strip" icon="gauge-high">
- Total AI-referred visits, top platform, unique platforms — all with 7-day delta.
+ <Card title="AI Referral Trend" icon="chart-line">
+ **By platform**: visits per day, or per hour on the 24-hour range. **vs Google clicks**: AI visits and Google clicks, each indexed to 100 on its first day with data. Dashed amber lines mark the days actions entered the Action Center or prompts were added. The Google line needs Search Console, and a range of 7 days or longer since Google reports clicks by day.
</Card>
- <Card title="Trend chart" icon="chart-line">
- Daily breakdown by AI platform, last 7 days.
+ <Card title="Platform Breakdown" icon="chart-pie">
+ Each AI platform's share of the range's visits.
</Card>
- <Card title="Platform table" icon="table-list">
- Per-platform visit counts with week-over-week change.
+ <Card title="Referrals by Platform" icon="table-list">
+ Visits and change per platform, with **Engaged** and **Key events** from Google Analytics.
</Card>
- <Card title="Top landing pages" icon="file">
- Which URLs on your site receive the most AI-driven traffic.
- </Card>
- <Card title="Recent visits log" icon="list">
- Real-time stream of the last 10–50 AI visits with platform, page, country, and timestamp.
+ <Card title="Top Landing Pages" icon="file">
+ The pages that receive the most AI visits, with their change and how often tracked AI answers cite them (**Cited in answers**).
</Card>
</CardGroup>
+<Note>
+AI Overviews and AI Mode clicks are part of Google organic clicks, and Google doesn't let them be separated. The Google line counts them all.
+</Note>
+
+### Where AI visitors convert
+
+Two tables from Google Analytics:
+
+- **Top converting pages from AI** — landing pages ranked by key events from AI visits, or by revenue when the property reports it, with the rate (shown from 30 visits) and the best platform.
+- **Which answers bring buyers** — the topics of your tracked prompts whose answers cite those converting pages, by the AI platform the visitors came from. It shows which topics bring buyers, not just visits.
+
+A range with fewer than 30 AI visits uses the last 30 days here, and says so.
+
+### Pages
+
+**Pages** answers which pages get AI visits, which don't, and why. Its tabs:
+
+| Tab | Lists |
+|---|---|
+| **No AI traffic** | Pages with traffic in Google Analytics or in your sitemap that got no AI visit, most valuable first — by revenue, orders, conversions or, without those, engagement. **AI visibility** says why: **Cited**, **Not cited** (prompts target it) or **No prompt**. |
+| **Cited, not clicked** | Pages AI answers cited at least 20 times in the range that got no AI visit. |
+| **Traffic, no prompt** | Pages AI assistants sent visitors to that no tracked prompt's answer cited: the visits come from questions you don't track. |
+| **Broken AI links** | Pages AI visitors landed on that don't exist, each with a suggested **Redirect to**. |
+| **All pages** | Every page with AI visits, citations, traffic or a sitemap entry in the range. |
+
+Rows carry their next step: **Audit page** for a page AI cites or a prompt targets, **Add prompts** for one no prompt points to. On **No AI traffic** and **Cited, not clicked**, each row's **…** menu also has **Send to Action Center**, **Add prompts** and **Suggest content**, and under the list **Audit N cited pages** (or **Audit N pages**) starts Site Audits for the cited pages shown, while **Send to Action Center** sends the pages shown as one action.
+
+**Add prompts** suggests questions people ask AI assistants that the page answers, including ones from its Search Console queries, and lets you add your own. The prompts you track from it point to the page, so their answers show whether AI cites it. Each one uses a prompt slot on your plan.
+
+**Broken AI links** reads what the visitor got:
+
+- **Not found (404)** or **Gone (410)**, from the status the browser reported;
+- **Shows a not-found page (200)** — a single-page app that answers every address with 200 and shows its own not-found page. It is listed once at least two visits saw it;
+- **Page title says not found** — where the browser reports no status (Safari, for one).
+
+The suggested redirect is a working page: a **Similar page**, **The page above it**, or the **Home page**. Addresses with a query string get no suggestion. With the tab open, the Excel and CSV buttons export the redirect list.
+
+### Google Search Console
+
+**Is AI changing your Google traffic?** Two tables, from Search Console's own data:
+
+- **Is AI taking Google clicks?** — pages whose impressions rose 15% or more while their CTR fell 20% or more, among pages with at least 100 impressions in the period before. An AI Overview may be answering in place of the click. **Positions** shows whether you're cited for a tracked prompt about the page; **Add prompts** appears when none is about it yet.
+- **Untracked Google queries** — queries with clicks that no tracked prompt covers, most clicked first. **Track** adds one as a prompt; **Track all** adds the listed ones that your plan's prompt slots allow. Admins and managers can track queries. Up to the 5,000 most clicked queries are checked.
+
+### AI bots reading your site
+
+From your own Cloudflare or Vercel. Only verified bots count: the user agent and the operator's published IP ranges must both match. Today that's OpenAI's GPTBot, OAI-SearchBot and ChatGPT-User, Anthropic's ClaudeBot, Claude-SearchBot and Claude-User, and Perplexity's PerplexityBot and Perplexity-User.
+
+- **By bot type** — hits, pages read and last seen for **Training**, **Search index** and **User fetch**, with the bots under each.
+- **Pages AI bots read** — hits per page, and when each type last read it.
+- **Search-bot alert** — pages AI answers cited in the last 30 days that no AI search bot read in those 30 days. It starts 30 days after the first AI-bot request, and pauses when the bot data doesn't cover the last 30 days or the month's cap was reached.
+
+Bot counts are kept by UTC day, so the 24-hour range reads yesterday and today (UTC), and All time reads the last 90 days. On the Starter plan the section shows sample data with **Upgrade**; without a connection, **Connect** or **Preview with sample data**.
+
+#### Connect AI bots
+
+<Steps>
+ <Step title="Open the dialog">
+ Click **Connect** on the **AI bots** card in the Data sources strip.
+ </Step>
+ <Step title="Choose how your site sends AI-bot requests">
+ - **Cloudflare Worker** (recommended) — a small Worker on your site's route passes every request through and sends only AI-bot requests, in batches.
+ - **Cloudflare Logpush** — Cloudflare sends only the AI bots' log lines, filtered at its edge. Nothing runs on your requests.
+ - **Vercel Drain** — Vercel sends your request logs; Ansvisor keeps the AI bots and drops the rest. Vercel Pro and Enterprise only.
+
+ Each option says what it costs on your own Cloudflare or Vercel bill before you connect. None of them changes your site's speed.
+ </Step>
+ <Step title="Create the connection and copy its settings">
+ Click **Create connection** and follow the numbered steps. **Copy the settings right away: the secret in them isn't shown again.** If you lose it, revoke the connection and create a new one.
+ </Step>
+</Steps>
+
+**Manage** on the card lists your connections with their last request, lets you **Revoke** one, and shows this month's use. Cloud plans store a monthly number of detailed rows; past it, detailed rows pause until the next month and the totals are still counted. Log records from Logpush or a Vercel drain have a monthly cap of their own. Only requests to your brand's own domains, or their subdomains, are kept.
+
+### Recent AI Referral Visits
+
+One row per visit, with time, platform, page and country. Search by URL or path, filter by platform, and page through the range ten at a time.
+
+## Alerts in the Action Center
+
+The nightly signals pass watches AI Traffic and raises these in the Action Center's **Signals**:
+
+| Signal | Raised when | Feeds |
+|---|---|---|
+| **AI visits fell from … to … week over week** | AI visits over the last 7 whole days (UTC) fell 40% or more from the 7 before, which had at least 30 | **Recover AI traffic** |
+| **Broken AI links on …** | AI visitors landed on a page that answered 404 or 410 in the last 7 days | **Fix broken citation targets** |
+| **AI search bots haven't read … that AI answers cite** | A page AI answers cited in the last 30 days wasn't read by any AI search bot in that time (needs 30 days of AI-bot data) | **Fix AI crawler accessibility** (needs Site Audit) |
+| **… started sending visitors** | An AI platform sent visits in the last 7 days for the first time | — |
+
+## Weekly AI Traffic e-mail
+
+Every Monday (UTC), each brand with AI visits gets an e-mail about the week before (Monday to Sunday, UTC):
+
+- three cards: AI visits with the change, the top platform, and the share of traffic (with Google Analytics) or how many pages are cited but not clicked;
+- the [summary line](#summary-line);
+- AI visits by day and by platform;
+- **Top changes** — up to three, broken AI links first, then the platforms and pages whose AI visits moved most;
+- **Open AI Traffic →**, which opens this page.
+
+It goes to the brand's [Daily Pulse](/guides/daily-pulse) recipients. To turn it off for a brand, untick **AI Traffic weekly digest** in **Settings → Notifications**; admins and managers can change it. It's on by default, and it isn't sent while the brand's Daily Pulse is **Off**.
+
+No e-mail goes out for a week with no AI visits in it or the week before, or when the organization's subscription isn't active. A send that fails on Monday is tried again on Tuesday and Wednesday. The e-mail is cloud only.
+
## Supported AI sources
-The pixel and the Google Analytics sync count the same AI assistants, from one list (`server/src/lib/ai-sources.json`):
+The snippet and the Google Analytics sync count the same AI assistants, from one list (`server/src/lib/ai-sources.json`):
- ChatGPT (chatgpt.com, chat.openai.com)
- Perplexity (perplexity.ai)
@@ -61,13 +214,19 @@ Google Analytics also counts its own **AI Assistant** channel, so an assistant t
## Privacy
-The pixel collects: referrer, URL, country (via IP geolocation), language, screen size, anonymized IP, user agent. **It does NOT use cookies, fingerprinting, or any cross-site identifiers.** No GDPR consent banner needed in most jurisdictions.
+The snippet sends nothing unless the visitor arrived from an AI assistant on the list above. For an AI-referred visit it sends the page address, the referrer, the AI source, the browser's user agent, language and screen size, and the page's HTTP status as the browser saw it. Ansvisor adds the country the request came from. **The snippet sets no cookies and stores nothing in the visitor's browser.**
+
+**The visitor's IP address is never stored.** To group a visit's pageviews into one visit, Ansvisor keeps a one-way key made from the IP address, your brand and a random salt that changes every day. Each day's salt is deleted after two days. From then on, nothing links a key to an address, and one visitor's days can't be joined. A visit that runs past midnight (UTC) counts as two.
+
+AI-bot requests from Cloudflare or Vercel are stored without IP addresses.
## Common patterns
- **Spike on a Friday** — usually a viral Reddit/Twitter thread that AI engines indexed and started recommending
- **Sudden country shift** — Perplexity or Gemini changed regional weighting; not a metric you control
- **Specific page surge** — one of your articles is being cited as authoritative; lock it in with internal links to defend
+- **Cited, not clicked keeps growing** — answers show your page but give no reason to click; add what the answer can't (tools, data, examples) and audit the page
+- **A new broken AI link** — an AI engine is citing an address you moved or retired; add the suggested redirect before the visits go elsewhere
<Card title="Continue: Competitors" icon="arrow-right" href="/guides/competitors">
Benchmark your AI presence against named rivals.
diff --git a/docs/guides/content-editor.mdx b/docs/guides/content-editor.mdx
new file mode 100644
index 000000000..347adf5d9
--- /dev/null
+++ b/docs/guides/content-editor.mdx
@@ -0,0 +1,183 @@
+---
+title: "Content Editor"
+description: "Plan what to write next, start a page yourself or with the Content Agent, write it to AEO rules, and keep it in the Library."
+---
+
+## The Content section
+
+**Content** in the sidebar has three pages:
+
+- **Plan** (`/dashboard/content/plan`): what to create, optimize or protect next, ranked.
+- **Opportunities** (`/dashboard/content`): the content opportunities Ansvisor finds in your visibility gaps. See [Content Optimization](/guides/content-optimization).
+- **Library** (`/dashboard/content/library`): every page you and the Content Agent wrote or changed in Ansvisor.
+
+Pages are written in the **editor** (`/dashboard/content/editor/<id>`). It opens from the Library, from the Plan, or when you start a page in **New content**.
+
+## Plan
+
+The **Content plan** lists the work for the last 7, 30 or 90 days. Pick the period at the top right.
+
+### Cards
+
+| Card | What it counts |
+|---|---|
+| **Create** | New pages AI needs: open opportunities with no page on your site yet. |
+| **Optimize** | Pages losing ground, and opportunities to improve a page you already have. |
+| **Protect** | Your top pages (cited at least 5 times in the period and not losing ground, up to 5), and opportunities to defend a page. |
+| **Priority** | Rows your team marked as a priority. |
+
+Click a card to filter the list to it; click it again to clear the filter.
+
+A page is **losing ground** when it is cited at least 20% less per tracked answer than in the period before, from at least 3 citations. Because the comparison is per tracked answer, a week with fewer runs, or prompts added or removed, doesn't move a page. If tracking began during the earlier period, a note above the list says so.
+
+### Priority list
+
+Each row shows:
+
+- the **Priority Score**;
+- the **Page**: its title, its page type, and its path, or **New page**;
+- the **Action**: Create, Optimize or Protect;
+- **Why** for the period, for example "Acme cited · you aren't", "Citation rate −35% on ChatGPT" or "Top page · 12 citations · 40 AI visits", tagged with where it comes from (**Opportunity**, **Citations** or **Protect**);
+- **Who** is on it: You, Agent, a teammate, or the person it is assigned to;
+- a button: **Create**, **Optimize** or **View** opens [New content](#new-content) on that row, and **Open draft** opens the draft already being written.
+
+Rows marked as a priority come first; the rest are ranked by score. The list shows up to 50 rows, for the whole plan or for a card.
+
+### Priority Score
+
+The score runs from 0 to 100 and is built from four factors:
+
+- **Severity**: how urgent the row is. A page losing citations counts most, more so the bigger the drop or the more citations it lost. Then come a new page AI needs, an existing page to improve, and a page to protect.
+- **Opportunity**: the score of the content opportunity behind the row. A row without one counts as neutral.
+- **Page value**: the page's AI visits in the period. A new page, or a brand with no AI traffic data, counts as neutral rather than zero.
+- **Citations**: how often AI answers cited the page in the period. A new page has none yet.
+
+Hover over the score, or focus it, to see **How this score is worked out**: each factor with the points it gave, and the total. The badge's level (critical, high, medium or low) uses the Plan's own cut-offs, and only a page losing citations can reach critical.
+
+<Note>
+This score ranks the Plan only. The Action Center scores its tasks on its own: see [Action Center](/guides/action-center).
+</Note>
+
+### Row menu
+
+- **Assign to…**: for a row with a draft, pick a teammate and the draft goes to the Action Center as a task for them. For a row without a draft, New content opens with **Team** chosen, so you pick the page type and the assignee there.
+- **Mark as priority** / **Remove priority** (admins and managers): the row moves to the top of the list, tagged **Priority**, and counts under the Priority card. **Send to Plan** on an opportunity does the same.
+- **Hide from the plan** (admins and managers): the row leaves the list and the counts. Undo it from the message that appears, or later from **hidden rows · Show** under the list, then **Show again**.
+
+### What AI cites in your topics
+
+Above the list, a line shows what visitors from AI assistants did on your site in the period: visits, and, with [Google Analytics](/guides/ai-traffic-analytics) connected, key events, orders and revenue.
+
+The **What AI cites in your topics** section opens with **Show**. For each page type it compares two shares: how much of the AI citations in your tracked answers go to that type of page, and how much of your own cited pages' citations it holds. A type AI cites 10 points or more beyond your own mix is marked as a **Gap**. Click a row to filter the priority list to that page type; click it again, or **Clear**, to remove the filter.
+
+The shares cover only the cited addresses whose type can be read. Forums, encyclopedias, news and the long tail of less cited pages are left out, and a line under the section says what share of the period's citations is covered.
+
+<Tip>
+The page types follow your brand's **Site type** (B2B SaaS, E-commerce or B2C) in the brand settings: feature and comparison pages for B2B SaaS, product and category pages for e-commerce, destination and help pages for B2C.
+</Tip>
+
+## New content
+
+**New content** opens from the Plan and the Library, from a Plan row's button, from **Send to Editor** on an opportunity, and from **Create content** in a prompt's menu on [Tracked Prompts](/guides/prompts).
+
+<Steps>
+ <Step title="Pick how to start">
+ **Create from scratch** writes a new page from:
+ - a **Content Opportunity**;
+ - a **Prompt**: prompts where AI already names or cites you in the last 30 days aren't listed, as they need no new page;
+ - a **Topic** that has tracked prompts.
+
+ **Optimize content** works on a page you already have:
+ - **Page URL**: a page on your brand's site (its domains are in the brand settings). **Import** brings in its main text, headings, links and schema; menus and footers stay out.
+ - **Paste text** from Word, Google Docs or a web page. Headings, lists, links and tables are kept.
+ - **Upload file**: Word, Markdown, HTML or text, up to 10 MB.
+ </Step>
+ <Step title="Pick the page type">
+ Click **Continue**. Ansvisor picks a **Page type** from the title, the content, the page or the opportunity, and says which. Pick another if it's wrong; you can also change it later in the editor.
+
+ For a new page, **Overview** lists your pages AI already cites for the same prompts, with how many of those prompts each one answers, its AI citations and its Google position. You can choose **Optimize *page* instead**, or **Create a new page**.
+ </Step>
+ <Step title="Choose who does it">
+ | Who does it | What happens |
+ |---|---|
+ | **Me** (default) | **Open editor** opens the draft for you to write. |
+ | **Agent** | **Start the agent**: the Content Agent writes a new page, or suggests changes to an existing one, in the background. The editor opens showing it at work; you can leave, and the draft waits in **Library › In review**. It uses this month's AI usage. |
+ | **Team** | **Send to Action Center**: the draft is saved in the Library and sent to the Action Center as an action. Pick a teammate in **Assign to**, or leave it unassigned. |
+ </Step>
+</Steps>
+
+If the agent can't start, for example because this month's AI usage is spent or the agent is already writing another of your team's drafts, the draft stays in the Library for you to write.
+
+## The editor
+
+The header shows the title, the page type, a **Rules** chip with how many rules the page meets now, and whether your changes are saved. The page saves as you write. Its buttons are **History**, **Copy HTML**, **Export** and **Mark ready**, and a button to show or hide the side panel.
+
+The page starts with its H1, which is also its title. A page has one H1: the toolbar won't add a second one. A paste is cleaned on the way in: headings, lists, links and tables stay; fonts, colors and styles go. Press ⌘/Ctrl + Shift + V to paste plain text. **Attach a file** inserts Excel, CSV, Word, Markdown, HTML or text, up to 10 MB each; a sheet comes in as a table.
+
+### Side panel
+
+The panel opens on **Rules**. Its tabs are **Rules · Brief · Sources · Live page**.
+
+- **Rules**: the rules the page is written to, for its page type. They come in five groups: page type rules, length and structure, fan-outs and keywords, links and sources, and style. Most rules can be turned on or off, and many have a value you can change; its status is read from the page as you write. Rules marked **AI check** are judged by the Content Agent and aren't counted yet. Changes apply to this draft only: **Save as my rules** keeps them for your workspace's next drafts of this type, and **Reset** goes back to the default set. Under **Your text rules**, write a rule in your own words, or **Paste many** from a style guide.
+- **Brief**: the page type, target URL, goal, audience, length, outline and keywords. **Edit brief** to change it. **Rebuild outline** writes a new outline from the sources you keep, each H2 answering a search AI ran for your prompts (a fan-out). **Rewrite from brief** (a new page) or **Suggest changes from brief** (an existing page) hands the page to the Content Agent; the page you have now stays in History.
+- **Sources**: what the draft is built from: **Prompts**, **Fan-outs**, **Cited pages** (what AI quotes today) and **Search Console** queries. Each source shows where the draft uses it. Uncheck one to leave it out, or **Add source** (a prompt, a page URL or a Search Console query), then **Rebuild with selection**.
+- **Live page**: for a draft that optimizes a live page, how that page does now: **Citations**, **AI visits**, **Google clicks** and **Prompts cited**, over 7 days to a year, against the period before. It is not a forecast of what the draft will get. Prompts that stopped citing the page are marked **Lost**, and **Use the lost prompts in this draft** adds them to the sources and rebuilds the brief. A new page has nothing to measure yet.
+
+Rebuilding the outline and running the Content Agent use your workspace's monthly AI usage.
+
+### Apply rules with Agent
+
+**Apply rules with Agent**, in the Rules tab, asks the Content Agent to suggest changes for the rules the page doesn't meet yet. Its suggestions appear in the page, each with **Accept** and **Reject**, under a bar with **Accept all** and **Reject all**.
+
+- A decided suggestion can be taken back with **Undo** or **Restore**; **Undo all** brings every one back to review.
+- One run makes at most 8 changes. Run it again for the rules still open.
+- Accept or reject the open suggestions before you run the agent again or edit the page as HTML.
+- The agent doesn't change heading levels: turn extra H1s into H2s in the toolbar yourself.
+- The agent only changes drafts, not published pages.
+
+### Passages AI cites are locked
+
+When a draft optimizes a live page, brought in by its URL, the passages AI answers quoted in the last 30 days are marked in green, for example "✓ Cited by ChatGPT 3× and Perplexity 1× in 30 days · keep wording". A chip in the header counts them.
+
+The Content Agent never changes these passages. If you edit one, the editor asks first: **Keep wording**, or **Edit anyway**. Changing a quoted passage may cost the page those citations.
+
+### History, HTML, Export and Mark ready
+
+- **History** keeps earlier versions for 90 days: the live page as imported, the page before agent changes, each Mark ready and publish, and the page before a restore. **Restore** makes a new version, so nothing is lost.
+- **Copy HTML** copies the whole page as HTML, HTML blocks and schema included, to paste into your CMS.
+- **Export** downloads the page as **Word**, **HTML** or **Markdown**. Only the HTML file carries the schema (JSON-LD).
+- **Add HTML** in the toolbar adds an HTML block: an embed, a widget or a form, kept exactly as written. Ansvisor never runs it. **Edit as HTML** shows the page's source; scripts, iframes and inline styles are removed when you switch back.
+- **Mark ready** saves the page, sets it to **Ready** and keeps a version in History. If the draft was sent to the Action Center, it also completes its task there. Ansvisor doesn't publish the page: copy or export it to your site.
+
+## Library
+
+The **Library** lists the drafts by status, each tab with its count:
+
+| Tab | What's in it |
+|---|---|
+| **All** | Every draft that isn't archived. |
+| **In progress** | Drafts being written. |
+| **In review** | Drafts the Content Agent wrote, waiting for a person. |
+| **Ready** | Drafts marked ready. |
+| **Published** | Drafts you marked as published. |
+| **Archived** | Drafts sent to the archive. They keep their status for when they're restored. |
+
+The columns are Content, Type, Method (Create or Optimize), By (you, the Content Agent or a teammate), Status, Created and Updated. Click a row to open the draft in the editor. The **Created** filter narrows the list to the last 7, 30 or 90 days.
+
+### Row menu
+
+- **Status**: set the draft to In progress, In review, Ready or Published. Ready works like the editor's Mark ready.
+- **Export Word**, **Export HTML** or **Export Markdown** for that draft.
+- **Send to Archive** or **Restore** (admins and managers).
+- **Delete** (admins and managers): the draft leaves the Library for good, with its versions and suggestions. An Action Center task it was sent as stays.
+
+### Export
+
+**Export** in the header downloads the drafts listed, that is the current tab within the **Created** range, with their pages:
+
+- **Export CSV** and **Export Excel**: one row per draft, with its title, status, method, page type, author, dates, page URL, length and text.
+- **Export Word**: one document, each draft starting on a page of its own.
+
+<Card title="Continue: Site Audit" icon="arrow-right" href="/guides/site-audit">
+ Score a page for AI search readiness and get fixes you can paste.
+</Card>
diff --git a/docs/guides/content-optimization.mdx b/docs/guides/content-optimization.mdx
index 09bb9fcab..b0faa76ae 100644
--- a/docs/guides/content-optimization.mdx
+++ b/docs/guides/content-optimization.mdx
@@ -3,6 +3,10 @@ title: "Content Optimization"
description: "Turn visibility gaps into editorial briefs delivered to your CMS."
---
+<Note>
+This page is **Opportunities** in the **Content** section. **Send to Editor** on an opportunity starts a page in the Content Editor, and **Send to Plan** puts it at the top of the Content plan. See [Content Editor](/guides/content-editor) for the Plan, the editor and the Library.
+</Note>
+
## What this module does
The **Content Optimization** page (`/dashboard/content`) lists *opportunities* — prompts where you have a visibility gap relative to competitors. Each opportunity carries:
diff --git a/docs/guides/mentions.mdx b/docs/guides/mentions.mdx
new file mode 100644
index 000000000..096abb512
--- /dev/null
+++ b/docs/guides/mentions.mdx
@@ -0,0 +1,185 @@
+---
+title: "Mentions & Sentiment"
+description: "Where AI answers name your brand, how they describe it, and what to do about it."
+---
+
+## What it shows
+
+The **Mentions & Sentiment** page (`/dashboard/mentions`, **Mentions** in the sidebar) reads the AI answers your tracking already stores and shows where they name your brand, in what tone, and next to which competitors. Opening the page or changing a filter never calls an LLM.
+
+It has three tabs:
+
+- **Overview** — the headline numbers, the trend, each AI platform, and how often AI names your competitors
+- **Mentions** — every answer that names your brand, one row each
+- **Perception** — the words AI uses next to your brand, compared with your top competitors
+
+The tab and the filters live in the URL, so a refresh or a shared link opens the same view. The **Mentions** and **Net sentiment** cards on [Answer Engine Insights](/guides/answer-engine-insights) open this page over the same dates.
+
+## Filters
+
+All three tabs share one filter bar. The brand is the active brand in the sidebar.
+
+| Filter | What it does |
+|---|---|
+| **Date range** | 24h, 7d, 30d (the default), 90d or Custom. A custom range is read as whole UTC days. |
+| **Platform** | One AI platform, or all of them |
+| **Country** | One tracked country. Shown only when the brand tracks more than one. |
+| **Topic** | One topic. Shown only when the brand has topics. |
+| **Search** | Matches the prompts' text. On the Perception tab the box reads *Search keywords…*, but it still searches the prompts. |
+
+The page header has three buttons:
+
+- **Copy summary** — copies the Overview as plain text: the filters, the summary line, the four KPIs with the number of responses behind each, and the period. Paste it into a doc, a ticket or a chat.
+- **Export CSV** — downloads the answers that name your brand under the filters, one row per answer, up to 5,000 rows per file. From the Mentions tab, the file also follows the table's sentiment and co-mention filters and its sort. Lines above the rows record the filters, the period and the counts, so the file still says what it covers when it is read later.
+- **Reports** — opens the [Reports](/guides/reports) page.
+
+The CSV's columns are `date_utc`, `prompt`, `topic`, `platform`, `model`, `country`, `sentiment`, `times_named`, `position`, `brands_named`, `co_mentioned` and `excerpt`. Dates are in UTC.
+
+## Overview
+
+<CardGroup cols={2}>
+ <Card title="Summary line" icon="align-left">
+ Net sentiment and its change, the platform behind most of that change, and the competitors AI usually names next to you. Written from the figures by a fixed template, with the period and the number of responses it rests on.
+ </Card>
+ <Card title="KPI cards" icon="gauge-high">
+ Total mentions, Mention rate, Prompts with mentions, and Net sentiment with its positive / neutral / negative split. Each one is compared with the previous period.
+ </Card>
+ <Card title="Mentions & sentiment over time" icon="chart-line">
+ One point per day. Switch between Mentions, Mention rate and Net sentiment. The trend needs at least two days, so the 24h view has none.
+ </Card>
+ <Card title="By AI platform" icon="table-list">
+ Mentions, mention rate, sentiment split and net sentiment for each platform. A platform with negative net sentiment is tinted, and a note appears when two platforms are 40 or more points apart.
+ </Card>
+ <Card title="Competitor framing" icon="users">
+ Your brand and each competitor: the responses naming it, its rate, and **Also names you**, which counts the competitor's responses that name your brand too and gives their share.
+ </Card>
+</CardGroup>
+
+Every change compares the selected period with the period of the same length just before it. It is taken only on the prompts that were answered in both periods, so adding or pausing prompts doesn't show up as a rise or a fall.
+
+## Mentions
+
+The **Mentions** tab lists every answer that names your brand, 100 per page.
+
+| Column | What it shows |
+|---|---|
+| **Prompt** | The tracked prompt the answer is for |
+| **Platform** | The AI platform that answered |
+| **Country** | Where the prompt ran. Shown only when the brand tracks more than one country. |
+| **Mention context** | The passage around the first place your brand is named, with your brand and competitors highlighted |
+| **Sentiment** | Positive, Neutral or Negative toward your brand. *Not rated* when the answer has no sentiment. |
+| **Position** | Where your brand comes among the brands the answer names: `#2 of 5` means second of five |
+| **Co-mentioned** | The competitors named in the same answer |
+| **Topic** | The prompt's topic |
+| **Date** | When the answer was tracked |
+
+### Table filters and grouping
+
+Next to the page filters, the table has its own controls:
+
+- **Sentiment** — all sentiments, Positive, Neutral or Negative
+- **Co-mentioned** — answers that also name a given competitor, answers that name **No competitor**, or **Any or none**
+- **Group by** — None, Prompt or Platform. Each group starts with its name and its size across all pages.
+- **Sort** — Newest, Oldest, Most co-mentions or Most negative
+
+The count beside them shows how many responses and prompts match. These controls are saved in the URL too.
+
+### Open a response
+
+Click a row to open the answer in a side panel:
+
+- the platform and model, the country, the date and time, and the prompt, with **View prompt** to open the prompt's page
+- the sentiment, your position and the topic
+- **Mention** — the passage around your brand, with your brand and competitors highlighted
+- **Also named in this answer** — the competitors and their positions
+- **Full AI response** — the answer as tracking stored it (it is not generated again)
+- **Citations in this answer** — each cited source, with the same source types as the [Citations](/guides/citations) page
+
+At the bottom of the panel are **Send to Action Center**, **Suggest content** and **Copy response**.
+
+### Correct a sentiment
+
+If an answer's tone toward your brand is wrong, click **Sentiment is wrong?** in the panel. Pick the new sentiment, add a note on why if you like, and click **Save correction**.
+
+- From then on, every figure counts the answer with its new sentiment. The original is kept in the history.
+- The panel shows who made the correction, when, what the sentiment was before, and the note.
+- Only admins and managers can correct a sentiment. Other members can see past corrections but not the button.
+
+### Suggest content
+
+**Suggest content** in the panel writes a content suggestion for the answer's prompt. When the suggestion is ready, the notification opens it in [Content Optimization](/guides/content-optimization). If the prompt already has a suggestion, **Open existing** takes you there instead. Suggestions count toward your monthly content limit. A prompt can't get a suggestion until it has tracked answers and a prompt group, and both arrive with its next tracking run.
+
+### Send to the Action Center
+
+Tick the rows you want. The box in the header selects every answer on the page. A bar appears with **Send to Action Center**, **Export** (a CSV of just the selected rows) and **Clear**. You can also send a single answer from its panel. One send takes up to 100 answers, a full page.
+
+The selected answers become one action, titled *Improve how AI describes you for "…"* (or *across N prompts*):
+
+- The action quotes up to 10 of the answers with their platform, sentiment and excerpt, and links back to Mentions.
+- It is a **Protect** action when any of the answers is negative, and a **Growth** action otherwise. The larger the share of negative answers, the higher its impact.
+- Its tasks walk you through inspecting the contexts you're mentioned in, analyzing the cited sources, choosing the pages to work on, strengthening how your brand is described, and publishing. They end by validating the mentions and measuring the outcome on the answers' prompts.
+- Sending the same answers again doesn't create a second action. The notification says **Already in the Action Center** and opens the existing action.
+
+## Perception
+
+The **Perception** tab shows the words AI uses next to your brand and how they compare with the words it uses for your competitors.
+
+<CardGroup cols={2}>
+ <Card title="What AI associates with you" icon="tags">
+ The words and phrases that appear next to your brand, ranked by the number of responses they appear in, each with its change from the previous period. Hover over a count to see its share of the responses naming you.
+ </Card>
+ <Card title="Brand shape: you vs top competitors" icon="shapes">
+ A radar chart of your brand and your three most-mentioned competitors, on the attributes that tell them apart. It needs at least three attributes and at least one competitor named in the period.
+ </Card>
+ <Card title="Brand × attribute" icon="table-cells">
+ The same attributes as a heat map: each attribute's share of the responses naming each brand, for you and up to four competitors.
+ </Card>
+ <Card title="Frequently mentioned with" icon="users">
+ The competitors named in the same responses as you, with the change from the previous period. It shows whether the set of brands AI considers alongside you is changing.
+ </Card>
+</CardGroup>
+
+Under the brand shape, **Biggest gap** names the attribute where a competitor leads you by the widest margin, if that margin is at least 20 points. For example, AI uses *affordable* in 45% of the responses naming a competitor but in only 10% of the responses naming you.
+
+The terms are taken from the sentences that name each brand, by fixed rules rather than an LLM. A sentence that names two brands lends its words to both.
+
+## How the numbers are counted
+
+Each tracked answer that names your brand is tagged **Positive**, **Neutral** or **Negative** toward your brand. An answer that doesn't name you has no sentiment. Competitors have no sentiment yet: every tone on this page is the tone toward your brand.
+
+| Term | How it is counted |
+|---|---|
+| **Tracked responses** | The AI answers stored for your prompts in the period, under the filters |
+| **Times named** | Every time an answer names your brand, by its name or one of its domains. An answer that names you three times counts three. The **Total mentions** card, the platform table's Mentions column and the CSV's `times_named` column count this way. |
+| **Mentions** (responses naming you) | Answers that name your brand at least once. An answer that names you twice is still one mention. The Mentions table lists these, and the Competitor framing table counts responses the same way. |
+| **Mention rate** | Responses naming you ÷ tracked responses |
+| **Prompts with mentions** | Prompts with at least one answer naming you, out of the prompts tracked |
+| **Net sentiment** | Positive share − negative share of the responses naming you, from −100 to +100. Neutral answers count in the total. It is shown as a signed number such as +21, not as a percentage. |
+| **Position** | Your brand's place among the brands an answer names (1 = named first) |
+
+### Low sample
+
+A figure that rests on fewer than 20 responses is marked **Low sample**. For the mention rate that means fewer than 20 tracked responses. For net sentiment it means fewer than 20 responses naming you. A low-sample figure is shown without a change from the previous period, isn't tinted in the platform table, and is left out of **Biggest gap**. With so few answers, a single negative response moves the number a lot.
+
+<Tip>
+If a figure says **Low sample**, widen the date range or clear a filter before you draw conclusions from it.
+</Tip>
+
+## API and MCP
+
+AI assistants can read the same figures through the [MCP server](/guides/mcp-server), and scripts can read them over REST with the same `ans_` API key. Both take the page's filters.
+
+| Tool | What it returns |
+|---|---|
+| `get_mentions_summary` | The Overview: times named, mentions, mention rate, prompts with mentions, sentiment, each platform and each day |
+| `list_mentions` | The Mentions table, 100 rows per page, with the sentiment, co-mention and sort options |
+| `get_mention` | One answer in full, with its citations and latest sentiment correction |
+| `get_mention_competitors` | Competitor framing |
+| `get_mentions_perception` | The Perception tab, including the biggest gap |
+| `override_mention_sentiment` | Corrects one answer's sentiment (**writes**; the key's user must be an admin or manager) |
+
+The Mentions & sentiment section of the [MCP server guide](/guides/mcp-server) lists the filters, the REST endpoints and an example request.
+
+<Card title="Continue: Citations" icon="arrow-right" href="/guides/citations">
+ See which third-party URLs AI engines trust to talk about your brand.
+</Card>
diff --git a/docs/guides/prompts.mdx b/docs/guides/prompts.mdx
index 36e8dc530..82724b062 100644
--- a/docs/guides/prompts.mdx
+++ b/docs/guides/prompts.mdx
@@ -1,22 +1,32 @@
---
title: "Prompts"
-description: "Manage tracked prompts and discover new ones with AI-powered suggestions."
+description: "Manage tracked prompts, read their estimated AI search volume, and turn a prompt into content."
---
-## Two tabs
+## Four tabs
-The **Prompts** page (`/dashboard/prompts`) has two tabs:
+The **Prompts** page (`/dashboard/prompts`) has four tabs. The **Prompts** item in the sidebar opens onto the same views: Tracked Prompts, Prompt Suggestions, Topics, Query Fan-outs and Insights.
-- **All Prompts** — flat list of every active prompt with visibility, mention rate, and platform breakdown
-- **Insights** — volume analytics + AI-powered prompt suggestions
+- **Prompts** — your prompt list. A switch above the filters picks **Tracked Prompts** (`/dashboard/prompts/tracked`) or **Prompt Suggestions** (`/dashboard/prompts/suggestions`)
+- **Topics** (`/dashboard/prompts/topics`) — your tracked prompts grouped by theme
+- **Query Fan-out** (`/dashboard/prompts/fan-outs`) — the searches AI engines ran behind their answers. Only Copilot and Perplexity share them
+- **Insights** (`/dashboard/prompts/insights`) — estimated AI search volume, intent and the highest-demand prompts
+
+The date range (24h, 7d, 30d, 90d or custom) applies to Prompts, Topics and Query Fan-out, and carries over when you switch tabs. Insights has no range: volume estimates aren't tied to a period.
+
+## Topics
+
+Topics is a tab of the Prompts page. The old `/dashboard/topics` address, and a topic's old `/dashboard/topics/<id>` page, redirect to `/dashboard/prompts/topics`. The tab uses the page's date range and opens on the last 24 hours. It has no Location selector, because topics aren't split by location.
+
+What each column means, and how to use topics for planning, is in the [Topics](/guides/topics) guide.
## Adding prompts
Three ways:
-1. **Manual** — click `+ Add prompt`, type the query, pick platforms/regions/AI models
-2. **Suggestions card** (Insights tab) — Ansvisor analyzes your tracked prompts, competitor citations, and topic gaps, then generates 6–12 new prompt ideas with a topic label, reason, and estimated monthly AI volume. Click `+` to add directly to your tracked set.
-3. **Bulk import** — paste a list of prompts, one per line, into the bulk-add dialog
+1. **Manual** — click `+ Add prompt`. On the **Single** tab, type the query and pick its topic, platforms, AI models and location
+2. **Bulk import** — the **Bulk import** tab of the same dialog takes a list of prompts, one per line
+3. **Prompt Suggestions** — add one suggestion with `+`, or every listed one with **Add All** (see below)
## Prompt status
@@ -28,6 +38,8 @@ Each row in **Tracked Prompts** has a status:
The table opens on Active + New. The **Status** filter, or the cards above the table, show one status or all of them. The **Added** column shows when each prompt was added; click it to sort by it. **Track** on a suggestion in the Visibility page's Opportunities opens Tracked Prompts in a new tab, with the new prompts on top.
+Click a prompt's text to open its own page, with its visibility, mentions, citations and per-platform results.
+
## Performance
The **Performance** filter groups prompts by where your brand is named in their AI answers over the selected range, across every platform the prompt tracks:
@@ -39,35 +51,146 @@ The **Performance** filter groups prompts by where your brand is named in their
Late and Missing list the furthest behind first. A prompt with no answers in the range, such as a new one, has no performance yet. The dots in the **Positions** column show each platform on its own.
-## Prompt Suggestions logic
+## Prompt Suggestions
+
+Open **Prompts → Prompt Suggestions**. Each refresh writes up to 25 prompt ideas, each with a topic label and a one-line reason. They come from three sources, and the **Source** filter shows one at a time:
+
+- **Ansvisor Agents** — written by AI from your brand and tracking data. Each shows an estimated monthly AI volume as a grey range (see [Estimated AI search volume](#estimated-ai-search-volume)).
+- **Google Search Console** — queries people already search, with their impressions a month.
+- **Google Analytics (GA4)** — pages that earn revenue or conversions, or already get AI visits, with that evidence on the row.
+
+When Search Console or Analytics is connected, a share of each refresh is drawn from their data. Use **Search prompts…** to narrow the list, `+` to add a suggestion, `×` to dismiss it and **New** to generate a fresh list. **Clear All** dismisses the AI suggestions listed; Search Console and Analytics suggestions are kept, so dismiss those one by one.
+
+### Add All
+
+**Add All** adds every suggestion listed to Tracked Prompts, and the added ones leave the list. Like Clear All, it acts on what's listed, so a source filter or a search narrows it. Each prompt passes the same plan check as a single `+`.
+
+When your plan's prompt limit stops it partway, an amber note sits above the list, for example:
-The suggestion engine considers four signals:
+> **15 suggestions couldn't be added**
+> 10 were added before your plan's prompt limit was reached. Upgrade your plan, or pause 15 prompts in Tracked Prompts first and try again.
+
+On Growth and Enterprise the note says "Contact us to raise your limit" instead of "Upgrade your plan". **Go to Tracked Prompts** opens the list where you can pause prompts; the note's other buttons upgrade the plan or contact us. Pausing as many prompts as the note names frees enough room for the rest. Self-hosted installs have no prompt limit, so everything listed is added.
+
+### How AI suggestions are written
+
+The suggestion engine considers five signals:
1. Brand context (name, description, language)
2. Existing tracked prompts (so it doesn't duplicate)
3. Existing topics (so it reuses your topic labels when relevant)
4. Top 12 competitors cited in your last 200 tracked AI responses
-5. Volume signal from `prompt_volumes` for tracked prompts (so suggestions skew toward high-volume territory)
-
-Output is calibrated: each suggestion comes with `text`, `topic`, `reason`, and a realistic `est_volume`. The reason explains *why* this prompt matters (gap, competitor activity, trend).
+5. The estimated volumes of your tracked prompts (so its own estimates stay in proportion)
<Tip>
-Suggestions have a 48-hour TTL. Hit **Refresh** on the Suggestions card to regenerate when you've made content changes or want fresh ideas.
+Suggestions have a 48-hour TTL. Click **New** to regenerate when you've made content changes or want fresh ideas.
</Tip>
+## Estimated AI search volume
+
+AI assistants don't publish how often people ask them something, so every AI search volume in Ansvisor is an **estimate**. It is shown as a range, such as **540–2k**, never as a single number, and carries a dashed **Estimate** badge.
+
+### How it's estimated
+
+The method note reads:
+
+> The median monthly Google searches for this prompt's related keywords × the share of Google searches that now get an AI answer (45%).
+
+- When a prompt's volume is analyzed, Ansvisor picks five short Google keywords for its category and reads their monthly Google searches. Keywords Google has no data for are left out, and the median of the rest is the prompt's Google volume (**Google Vol.**).
+- The share of Google searches that get an AI answer is 45% by default. The Insights tab shows it as **AI Adoption Rate**; a self-hosted server can change it with `AI_VOLUME_MULTIPLIER` (see [Environment variables](/self-host/env-variables)).
+- The range is the AI share of the middle half of the keywords, kept within half to twice the estimate and at least 25% either side of it. With only one keyword to go by, the range is half to twice the estimate.
+
+### Confidence
+
+| Confidence | When |
+|---|---|
+| **High** | At least 3 of the prompt's keywords have Google search data, and the middle half of them are within 4× of each other |
+| **Medium** | At least 2 have data, within 15× of each other |
+| **Low** | Anything else, including an estimate of 0 |
+
+Volumes fetched over six months ago count one level less; **Refresh Volumes** on the Insights tab gets newer ones.
+
+A low-confidence estimate is grey, its badge reads **Estimate · low confidence**, and it isn't used to rank on its own: **High Opportunity Prompts** leaves it out, and sorting Tracked Prompts by **Volume** puts it after the confident estimates, before prompts with no volume.
+
+### Reading a range
+
+Hover or focus a range or its badge (it is keyboard-reachable) to open the method note. It says how the estimate was built, how many of the related keywords have Google search data, the sources and their month, and the confidence with its date.
+
+**Measured numbers never carry the badge** — for example your visibility, mentions and citations, Search Console clicks and impressions, or a suggestion's Analytics sessions. If a number has no Estimate badge, it was counted, not estimated.
+
+Some estimates are built differently, and their note says so:
+
+- **Totals and averages** (Insights' **Total Est. AI Volume** and **Avg. AI Volume**, Similar Topics' **Est. AI Volume**) — the sum of the lows to the sum of the highs. The total is high-confidence when at least 80% of its volume is high-confidence, low when more than half is low-confidence, and medium otherwise. The note gives the mix, such as "2 high, 3 medium, 1 low".
+- **One keyword** (each row of Similar Topics) — the keyword's Google volume is measured and only the AI share is assumed, so it is Medium with a ±25% range (Low without volume data, or over six months old).
+- **An AI's guess** (Prompt Suggestions from Ansvisor Agents, and the Visibility page's Opportunities) — no keyword behind it is measured yet, so it is always Low: grey, half to twice the guess. Track the prompt to get an estimate from its keywords' Google searches.
+
+### Where you see estimates
+
+- **Tracked Prompts** — the **Volume** column
+- **A prompt's page** — an **AI searches a month** card, when the prompt has a volume
+- **Insights** — **Total Est. AI Volume**, **Avg. AI Volume**, the **Prompt Volumes** table's **Est. AI Vol.** column, **High Opportunity Prompts**, and the Prompt Volumes chart's tooltip
+- **Similar Topics** — the Insights card's **See all** page (`/dashboard/prompts/similar-topics`)
+- **Prompt Suggestions** — each AI suggestion's `/mo` range
+- **Outside Prompts** — the Action Center's affected prompts and topic opportunities, the Visibility page's Opportunities, and a content opportunity's **Est. AI Volume**
+
+### Estimates in exports
+
+Exports mark estimated volumes, so a spreadsheet doesn't read them as counts:
+
+- **Tracked Prompts → Export CSV** adds `volume_type` (`estimate`), `volume_confidence`, `est_ai_volume_low`, `est_ai_volume_high` and `volume_date` after `est_ai_volume`. `est_ai_volume` stays the single point estimate that sorting and totals use.
+- **Action Center → Export CSV / Export Excel** gives the volume as a range, followed by `volume_type` and `volume_confidence`.
+- **A content opportunity's Copy All Data and exports** give **Est. AI volume** as a range, with **Volume type** and **Volume confidence**.
+- The [MCP server](/guides/mcp-server)'s `get_prompt_volumes` returns `est_ai_volume_low`, `est_ai_volume_high`, `volume_confidence` and `volume_type` with each row.
+
## Volume Analysis (Insights tab)
-For prompts where you've enabled volume analysis, you'll see:
-- **Estimated monthly AI volume** (rough): the prompt's Google volume × the AI adoption multiplier (45% by default, about the share of Google searches that show an AI Overview). The Google volume is the median of the monthly searches for five category keywords picked for the prompt; keywords Google can't measure are left out. The Insights total adds up these per-prompt estimates.
-- **Intent classification** (informational, commercial, navigational, transactional)
-- **Keyword cluster** — the related queries that group with this prompt
+Volumes come from an analysis you run: **Analyze Volumes** the first time, **Analyze New Prompts** for prompts added since, **Refresh Volumes** for newer Google data, and **Re-analyze Keywords** to analyze every prompt again, keywords included. Each analysis counts against a monthly quota on cloud plans; the toolbar shows how many are left. Tracked Prompts also warns when some prompts haven't been analyzed yet.
+
+For analyzed prompts you'll see:
+
+- **Estimated monthly AI volume**, as a range with its confidence (above)
+- **Intent** — Comparison, How-to, What is, Best / Top, vs. / Review, Recommendation, Problem Solving or Other
+- **Similar Topics** — the most-searched keyword clusters across your prompts
+
+## Create content from a prompt
+
+Each row in **Tracked Prompts** has a **…** menu: Edit, Pause tracking, Improve position…, Suggest content, **Create content** and Delete.
+
+<Steps>
+ <Step title="Click Create content">
+ It opens **New content** at its Start step, titled with the prompt (for example **Create: best espresso machine for beginners**).
+ </Step>
+ <Step title="Pick a page type">
+ Ansvisor picks one from the title; change it if it's wrong. You can also change it later in the editor.
+ </Step>
+ <Step title="Check the overlap">
+ Start reads your pages AI already cites for the prompt. If one already answers it, you can choose **Optimize** that page instead of **Create a new page**.
+ </Step>
+ <Step title="Choose who does it">
+ **Me** opens the Content Editor, **Agent** writes a draft for you to review, and **Team** sends it to the Action Center.
+ </Step>
+</Steps>
+
+If a draft that isn't published yet already covers the prompt — one started from the prompt, its topic or an opportunity — the menu shows **Open draft** instead, so you don't start a second page.
+
+### From the Improve tab
+
+**… → Improve position…** opens the prompt's positions panel. Its **Improve** tab starts with a content step, decided from the answers in the panel's period:
+
+| What the answers show | Step |
+|---|---|
+| No answer mentions or cites your brand | **Create content** — start a new page |
+| Your brand is named in under 20% of the answers, with 5 or more answers | **Optimize content** |
+| Your average position is worse than #3, over 3 or more answers that name you | **Optimize content** |
+| Anything else | No content step |
-Click any prompt to see per-platform results with the full AI response, parsed citations, and competitor mention list.
+**Optimize content** opens Start on the page of yours AI engines cite most for the prompt. When none is cited, Start lists your pages that answer the prompt so you can pick one. When a draft already covers the prompt, the step offers **Open draft**.
## Best practices
- Aim for **20–80 active prompts** per brand. Below 20 you miss coverage; above 80 noise drowns insights.
- Mix prompt types: comparison, how-to, best-of, recommendation, alternative, problem-solving
+- Read volumes as ranges: compare prompts by their confidence as well as their size, and prefer high-confidence estimates when you prioritize
- Re-evaluate quarterly: archive prompts that consistently score 0 and bring nothing actionable
<Card title="Continue: Citations" icon="arrow-right" href="/guides/citations">
diff --git a/docs/guides/site-audit.mdx b/docs/guides/site-audit.mdx
new file mode 100644
index 000000000..3ad81e96f
--- /dev/null
+++ b/docs/guides/site-audit.mdx
@@ -0,0 +1,177 @@
+---
+title: "Site Audit"
+description: "Score any page for AI search readiness across 47 signals, and get page-specific fixes you can paste."
+---
+
+## What it does
+
+The **Site Audit** page (`/dashboard/audit`) checks how ready a page is to be cited by AI answer engines. It fetches the page, runs **47 signals** in five categories, scores the page out of 100, and writes fixes for what failed: an improved H1, a meta description, an opening paragraph that leads with the answer, FAQ markup and more.
+
+You find it in the sidebar under **Execution**, after **Content**. It is available on plans that include Content Optimization.
+
+You can audit any URL: your own pages, or a competitor's page to see what it does better. Audits of other sites are listed with your pages but kept out of your site's score.
+
+## Run an audit
+
+<Steps>
+ <Step title="Enter a URL">
+ The field at the top is filled in with your brand's primary domain. Replace it with the page you want to check and click **Run Audit**.
+ </Step>
+ <Step title="Wait for the report">
+ The report page opens right away and follows the audit through its stages: **Fetching the page…**, **Analyzing 47 signals…** and **Generating AI recommendations…**. An audit usually takes about 30 seconds. If it is still running after two minutes, the page says **This audit is taking longer than expected.** Click **Check again** to look again.
+ </Step>
+ <Step title="Read the report and fix">
+ Start with the **AI Recommendations**, then open the failing signals. When you've made changes, click the re-run icon at the top of the report to audit the page again.
+ </Step>
+</Steps>
+
+You can also start audits from:
+
+- the **Opportunities** tab, with **Audit selected** (see [Opportunities](#opportunities));
+- the **Pages** tab, with **Re-audit** on the pages you select;
+- the **AI Referral Traffic** page, with **Audit page** on a landing page;
+- auto-audit, which audits your top-priority pages on its own (see [Auto-audit and settings](#auto-audit-and-settings));
+- the [MCP server](/guides/mcp-server#site-audit), with `run_site_audit`.
+
+Audits started in bulk run a few at a time.
+
+<Note>
+Each completed audit uses one of your plan's monthly audits. An audit still running already counts; a failed one doesn't. The **Audits this month** card shows what's left. Self-hosted instances have no monthly limit, but they need a Scrape.do key to fetch pages — see [Environment variables](/self-host/env-variables).
+</Note>
+
+## The Site Audit page
+
+### Summary and cards
+
+A one-line summary at the top gives your site score, the number of pages audited, your lowest category and when the next auto-audit runs. Below the URL field, four cards sum up your audits. The first three count only the pages of your **primary domain**:
+
+| Card | What it shows |
+|---|---|
+| **Site score** | The average score of each page's latest audit, and its change from each page's previous audit |
+| **Pages audited** | Pages of your domain with a completed audit, and how many pages of other sites you audited |
+| **Authority · E-E-A-T** | The two category scores averaged over your pages, and the signals that fail or warn on the most pages |
+| **Audits this month** | Audits left this billing month, with the share auto-audit keeps for its runs still to come |
+
+**Score over time** charts your primary domain's audit scores (one point a day, the latest audit that day) over 7d, 30d, 90d or All, with the category breakdown of the latest audit beside it. The chart needs audits on at least two days.
+
+### Opportunities
+
+The **Opportunities** tab is an inbox of the pages worth auditing next. Each row shows a **Priority** (0–100), the page, **Why** it's listed, its **AI visits** over the last 30 days and its **Last audit**. A page is listed because:
+
+- **No AI traffic** — a page that ranks high on your site in Google Analytics (for example **Top 5% by revenue**) but gets no visitors from AI engines. **Targeted, not cited** adds that a tracked prompt points at the page and no AI answer cites it;
+- a competitor is cited on prompts where you never are, and this is your closest page (for example **Acme cited on 3 prompts**);
+- **Never audited**, or **Audited 120 days ago** — pages of your site with no audit in the last 90 days.
+
+The priority multiplies the page's value to the business, the size of the opportunity and how easy it is to fix (how close its last score is to passing). Hover the number to see the three parts.
+
+Pages built from one template, such as every post under `/blog/*`, share most of their gaps. When at least two-thirds of a template's audited pages fail the same signals, the template gets one row: **Fix once, applies to 38 pages**. Auditing it audits the template's pages that have no audit yet.
+
+Select rows to **Audit selected**, **Pin** them (pinned pages always come first) or **Exclude** them. Excluded pages are listed under the table, where **Restore** puts them back.
+
+<Note>
+AI visits need Google Analytics or the [tracking snippet](/guides/ai-traffic-analytics). Without either, the column stays empty and pages are ranked without them.
+</Note>
+
+### Pages
+
+The **Pages** tab lists every page you audited, one row per page however many times you audited it, most recent first:
+
+| Column | Meaning |
+|---|---|
+| **Score** | The latest audit's score |
+| **Issues** | Signals that failed or warned in that audit |
+| **Status** | **Good** (70 or more), **Improving** (below 70 but up from the previous audit), **Needs work**, **Running** or **Failed** (no audit of the page has completed) |
+| **Last audit** | When it was last audited; **Auto** marks an auto-audit run's audit |
+
+Click a row to open its latest report. The arrow beside a page lists its earlier audits, each with **View report** and a delete icon. **Group by template** groups the rows under their template (`/blog/*`) and names the gaps its pages share. **Export** downloads the list as CSV or Excel; select pages to **Re-audit** or export only those.
+
+## The audit report
+
+Each audit has its own report at `/dashboard/audit/[id]`. The icons at the top re-run the audit on the same URL or delete it (**Delete audit** can't be undone).
+
+### Total score
+
+The gauge shows the page's score out of 100 and a grade: **Good** (70 and above), **Needs work** (40–69) or **Poor** (below 40). Beside it are the number of signals that **passed**, raised **warnings** or **failed**, and how many of the 47 signals were evaluated.
+
+### Categories
+
+**Category breakdown** scores each category out of 100, with how many of its signals were evaluated:
+
+| Category | Weight | What it checks | Examples |
+|---|---|---|---|
+| **Structure** | 25% | Whether an AI engine can parse the page | Heading hierarchy, JSON-LD, FAQ schema, lists and tables, alt text, Open Graph |
+| **Content** | 25% | Whether the page answers its question directly and completely | Direct answer, BLUF, sub-query coverage, in-line definitions, readability |
+| **Authority** | 20% | Whether the page reads as expert and sourced | Author byline, citations, statistics, quotations, freshness |
+| **E-E-A-T** | 20% | Experience, expertise and trust signals | First-person evidence, case studies, author credentials, your brand in Wikidata, privacy and contact pages |
+| **Trust** | 10% | Crawl-time and share-time basics | AI bot access in robots.txt, llms.txt, HTTPS, canonical URL, meta description |
+
+A category's score is the average of its signals; the total is the weighted average of the categories. A signal that couldn't be evaluated (**n/a**) is left out, so it never lowers the score.
+
+Most signals are read straight from the page, its robots.txt and its llms.txt. Thirteen, such as **Direct answer to query** and **Case study evidence**, are judged by an AI model that first works out what the page itself is about, so a page is never judged against a topic it isn't trying to cover. **Brand entity in Wikidata** looks your brand up in Wikidata.
+
+### Signals
+
+The **Signals** section lists every check by category, each with a pass, warning, fail or n/a icon and its impact (**high**, **medium** or **standard**). **Issues only** hides the passing ones. Open a signal to see:
+
+- **Finding** — what this audit saw on the page, when the check reports it;
+- what the signal measures, and **Why** it matters to AI engines;
+- **Recommended fix** — the page-specific AI recommendation, with any draft or code to paste; or **Fix** — the general fix, for signals without one.
+
+### AI Recommendations
+
+**AI Recommendations** collects the page-specific fixes at the top of the report, ordered by priority (**high**, **medium**, **low**). Each names the signal, says what to change in one sentence and, where it helps, gives a ready-to-paste **draft** (a meta description, an H1, an opening paragraph, FAQ questions and answers, sources to cite) and **code** (such as an FAQPage JSON-LD block).
+
+Recommendations are written for the content signals an AI model can help with. Mechanical ones — HTTPS, the viewport tag, alt text, a video embed — keep their general fix. Every sentence is kept to 150 characters.
+
+### Placeholders in [brackets]
+
+Recommendations only use facts found on the page, or in your brand's name, description and domains when the page is on one of your domains. A number, percentage, price, date or company name that appears in neither becomes a **placeholder** in square brackets, highlighted in the draft:
+
+```text
+Teams at [customer name] cut onboarding time by [real metric] after switching.
+```
+
+Common placeholders are `[customer name]`, `[real metric]`, `[price]`, `[date]` and `[source URL]`. When a draft or code block holds one, the report reminds you: **Replace placeholders in [brackets] with your real data before publishing.**
+
+<Tip>
+Search the pasted text for `[` before you publish. A placeholder left in a JSON-LD block, such as `"price": "[price]"`, is valid JSON but tells AI engines nothing.
+</Tip>
+
+### Copying drafts and code
+
+Each draft and code block has a copy icon in its corner (**Copy draft** or **Copy code**). It copies the block exactly as shown, placeholders included; a **Copied** toast confirms it.
+
+## Auto-audit and settings
+
+Auto-audit spends a quarter of your monthly audits on the Opportunities inbox's top pages, in five runs on days 1, 7, 14, 21 and 28 of your billing month. Pinned pages go first; pages audited in the last 30 days wait for a later run. After a run, a notice on the Site Audit page sums it up (pages audited, critical issues, the next run) with **View pages**, and the audits show **Auto** in the Pages list.
+
+**Settings** (top right) holds:
+
+- **Auto-audit** — on or off for every brand in your organization. Turned off, all your monthly audits are yours to spend. On plans with no monthly limit, it starts off.
+- **E-mail the team after each run** — a summary e-mail after each auto-audit run.
+- **Excluded pages** — one path per line, `*` for anything (`/legal/*`). These pages stay out of Opportunities and auto-audits.
+- **Pinned pages** — the pages you pinned from Opportunities, with **Unpin**.
+
+Only admins and managers can change these settings; other members see them read-only.
+
+## How audits feed the Action Center
+
+Each night the Action Center reads the latest audit of each page from the last 90 days and turns failed signals into actions:
+
+| Action | Raised when |
+|---|---|
+| **Fix low-scoring pages** | Audited pages score below 50/100. One action covers all of them, worst first. |
+| **Fix AI crawler accessibility** | **AI bot access (robots.txt)** fails |
+| **Fix structured data issues** | A JSON-LD or **FAQ schema** signal fails |
+| **Fix outdated content** | **Freshness** or **Date markup** fails |
+| **Fix weak entity signals** | **Brand entity in Wikidata** or **Entity coverage** fails |
+| **Fix internal content connectivity** | **Internal linking** fails |
+| **Fix content gaps** | **Query token coverage** or **Sub-query coverage** fails |
+
+An action lists the pages it covers and the failed checks on each, with a link to **Open Site Audit**. Re-audit the pages after you fix them: only each page's latest audit counts, so once the new audit no longer fails the check, the Action Center stops reporting that page. An audit older than 90 days no longer counts either.
+
+The **Audit Score** section of [Reports](/guides/reports) brings your audit scores into a report.
+
+<Card title="Continue: Reports" icon="arrow-right" href="/guides/reports">
+ Turn your AI visibility and audit scores into shareable snapshot reports.
+</Card>
diff --git a/docs/mint.json b/docs/mint.json
index b9b8db5f3..822656d2a 100644
--- a/docs/mint.json
+++ b/docs/mint.json
@@ -77,13 +77,17 @@
"group": "Platform Guides",
"pages": [
"guides/add-your-first-brand",
+ "guides/action-center",
"guides/answer-engine-insights",
"guides/topics",
"guides/prompts",
+ "guides/mentions",
"guides/citations",
"guides/ai-traffic-analytics",
"guides/competitors",
"guides/content-optimization",
+ "guides/content-editor",
+ "guides/site-audit",
"guides/reports",
"guides/daily-pulse",
"guides/mcp-server",