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.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
docs(guides): bring the stale guides in line with the app as it is today (#1795)
Cihanbcf7c1baf332
diff --git a/docs/concepts/visibility-scoring.mdx b/docs/concepts/visibility-scoring.mdxindex 6922ccfe5..56222e2e1 100644--- a/docs/concepts/visibility-scoring.mdx+++ b/docs/concepts/visibility-scoring.mdx@@ -5,37 +5,33 @@ description: "How Ansvisor computes a 0–100 visibility score per brand, prompt## The score in one sentence-Visibility score is the percentage of tracked AI responses that mention your brand by name, weighted by mention prominence and citation strength.+The **AI Visibility Score** (0–100) blends three things over the answers in your date range and filters: how many answers name your brand, how many cite a page of yours, and how early you're named.-A score of **0** means your brand never appears. **100** means it's mentioned in every response, prominently, with at least one citation. Most brands sit between 15–60% in healthy categories, so don't be alarmed if you start low.+A score of **0** means no answer names or cites you. The closer every answer comes to naming you first and citing you, the closer the score gets to **100**.-## How a single response is scored--Each time a prompt runs against an AI engine (e.g. "best CRM for small business" against ChatGPT), Ansvisor parses the response and computes a per-response score from three components:+## How it's computed<Steps>- <Step title="Mention count (50% weight)">- How many times your brand is named in the response. Capped at 5 to prevent spammy responses from skewing the score.+ <Step title="Mention rate (60%)">+ The share of answers that name your brand.</Step>- <Step title="Position bonus (25% weight)">- Where in the response your brand appears. First mention in the answer counts more than a brand listed eighth in a long alternatives section.+ <Step title="Citation rate (25%)">+ The share of answers that cite a page of yours.</Step>- <Step title="Citation presence (25% weight)">- Whether the response includes a citation URL pointing to a domain you own or a third-party source that mentions you alongside the citation.+ <Step title="Position (15%)">+ How early you're named, in the answers that name you: being named first counts 1, second ½, third ⅓, and so on, averaged. While only a few answers name you, this part counts for less, so one lucky first place can't lift the score on its own.</Step></Steps>-The result is a 0–100 number per `(prompt, platform, run)` triple.+The score is 100 × (0.6 × mention rate + 0.25 × citation rate + 0.15 × position), to one decimal. All three parts read the same answers, so the filters you set apply to each of them.-## Aggregation+## A single answer's score-Dashboard visibility scores aggregate across multiple dimensions:+Each answer also gets its own 0–100 score, shown with that answer: up to 40 points for naming you (10 per mention), up to 30 for citing you (15 per citation), up to 15 for your share of the answer's citations, and up to 15 for its tone (15 when positive, 7 when neutral and you're named).-- **Per prompt**: average score across all platforms over the last 7 days-- **Per platform**: average across all prompts on that platform over the last 7 days-- **Brand-level**: weighted average across all prompts and platforms in the active set+## Comparing periods-Trend deltas (the green/red `+12%` you see on cards) compare the most recent 7-day window against the previous 7 days, on identical prompt sets, so the number is apples-to-apples.+The change shown beside a score (green or red) compares your date range with the period before it, **vs previous period**, on the prompts answered in both, so the comparison is like for like.## What moves your score@@ -59,10 +55,9 @@ Trend deltas (the green/red `+12%` you see on cards) compare the most recent 7-d## Where to see it-- **Insights**: brand-level score with sparkline + delta-- **Topics**: average score per topic cluster-- **Prompts**: per-prompt score with platform breakdown-- **Brands page**: card-level score for cross-brand comparison+- **Brand Visibility**: the brand's score, its trend and the change vs the previous period+- **Prompts › Tracked Prompts**: each prompt's score+- **Competitors**: each tracked competitor's score beside yours<Card title="Continue: Topics and Prompts" icon="arrow-right" href="/concepts/topics-and-prompts">How prompts cluster into topics and why that matters.diff --git a/docs/guides/add-your-first-brand.mdx b/docs/guides/add-your-first-brand.mdxindex 3bf397566..36f7528e1 100644--- a/docs/guides/add-your-first-brand.mdx+++ b/docs/guides/add-your-first-brand.mdx@@ -11,33 +11,33 @@ description: 'Step-by-step walkthrough of brand onboarding.'## Onboarding flow-The onboarding wizard has **5 steps for self-hosted** instances and **7 steps for the cloud** (the extra steps are what you work on and plan checkout). Each step auto-saves so you can resume later if you drop off.+The onboarding wizard has **5 steps for self-hosted** instances and **7 steps for the cloud** (the extra steps are what you work on and plan checkout). From step 2 on, your progress is saved as you go, so if you drop off you resume where you left off.<Steps><Step title="1. Brand basics">- Three fields:+ **Set up your brand** asks for three fields:- - **Brand name** — exactly how the brand is named in the wild (e.g. *Mercedes-Benz*, not *MBZ*). Casing matters — suggestions copy your spelling, mention detection is case-insensitive.- - **Website** — your main domain without `https://` prefix (e.g. `mbusa.com`, `linear.app`). Used for citation classification, AI traffic attribution, and competitor research.- - **Describe your brand** *(optional but recommended)* — 1–3 sentences covering what you do and who your audience is. Fed into AI to generate better topics, prompts, and competitor suggestions.+ - **Brand name** — exactly how the brand is named in the wild (e.g. *Acme Coffee*, not *AC*). Mention detection ignores upper and lower case.+ - **Website** — your main domain; the `https://` prefix is already filled in (e.g. `example.com`). Used to recognize citations of your site and to suggest competitors.+ - **Describe your brand** *(optional but recommended)* — 1–3 sentences covering what industry you're in and who your audience is. A description helps Ansvisor generate better topic, prompt and competitor suggestions.- The industry isn't asked as a separate field — Ansvisor infers it from your description.+ There's no separate industry field: put your industry in the description.</Step><Step title="2. Region & language">- Pick the primary market and language for tracking. This drives:+ **Select your target market**: pick the region and language your audience uses. For the United States you can also pick a state, which localizes AI answers to it; leave it empty for nationwide results. This drives:- - Which language AI engines respond in (English prompts return English answers, etc.)- - Region weighting on search engines that have it (Google AI Overviews / AI Mode geo-localize)- - DataForSEO query routing for prompt volume estimation+ - The language your suggested topics and prompts are written in, and so the language AI engines answer in+ - The location your prompts are asked from+ - The competitors suggested in step 5- 18 regions and 13 languages supported. You can change these later per-prompt if you have multi-region needs.+ 18 regions and 13 languages supported. You can track prompts in more locations later; see [Prompts](/guides/prompts).</Step><Step title="3. Topic selection">- Ansvisor uses your brand description and an AI model to suggest 6–10 **topics** — themes your customers care about (e.g. *EV Range*, *Reliability*, *Pricing*).+ **Choose topics to monitor**: Ansvisor uses your brand details and an AI model to suggest **topics** — themes your customers care about (e.g. *EV Range*, *Reliability*, *Pricing*). The first seven come checked.- Review the list and check the topics that fit your brand. Uncheck any that don't apply. You can also type a custom topic name and add it manually.+ Check the topics that fit your brand and uncheck any that don't apply, up to 10. You can also type a custom topic name and add it with **+**. If suggestions can't be fetched, add your own. **Looks good** moves on.<Tip>Aim for 4–7 topics. Too few = narrow tracking surface. Too many = noisy and hard to interpret.@@ -45,14 +45,16 @@ The onboarding wizard has **5 steps for self-hosted** instances and **7 steps fo</Step><Step title="4. Prompt review">- For each selected topic, Ansvisor generates **5 starter prompts** (real questions a potential customer would ask an AI engine). Review the full list:+ **Review your prompts**: for each selected topic, Ansvisor generates **5 starter prompts** (real questions a potential customer would ask an AI engine), so 10 topics give 50 prompts. Review the list:- - Edit prompt text inline if a phrasing feels off- - Delete prompts that don't fit- - Add custom prompts at the bottom+ - Remove prompts that don't fit+ - Remove a whole topic from its **…** menu › **Remove topic**+ - Add your own prompts under each topic++ If the list holds more prompts than your plan allows, the step says how many to remove before you can continue.<Note>- These prompts will run on every AI platform allowed by your plan. Self-hosted unlocks all 8 (ChatGPT, Google AI Overviews, Google AI Mode, Google Gemini, Perplexity, Microsoft Copilot, Grok, Claude). Starter plan runs ChatGPT + Microsoft Copilot by default; Growth and Enterprise unlock the rest.+ These prompts are sent to AI platforms daily, on every platform your plan allows. Self-hosted runs all 8 (ChatGPT, Google AI Overviews, Google AI Mode, Google Gemini, Perplexity, Microsoft Copilot, Grok, Claude). On the cloud, Starter runs ChatGPT and Microsoft Copilot; Growth and Enterprise add Google AI Overviews, Google AI Mode, Gemini, Perplexity and Grok. Claude is an Enterprise option on the cloud.</Note><Tip>@@ -61,39 +63,42 @@ The onboarding wizard has **5 steps for self-hosted** instances and **7 steps fo</Step><Step title="5. Competitors">- Ansvisor analyzes your brand and suggests 3–8 competitor names. Review the list:+ **Add your competitors**: Ansvisor analyzes your brand and suggests competitor names. Review the list:- Check the ones that are actual rivals- - Uncheck ones that aren't really comparable- - Add custom competitors at the bottom (use the name as it appears in AI responses, e.g. *Salesforce*, not *salesforce.com*)+ - Uncheck or remove ones that aren't really comparable+ - Add your own with a company name and domain (use the name as it appears in AI responses, e.g. *Acme*, not *acme.com*)++ Select at least one competitor to continue; **Start tracking with N competitors** finishes the brand. Competitor tracking is on every plan.- Competitor tracking is unlocked on Growth and Enterprise plans on the cloud, and always available on self-hosted.+ If your site looks like an online store, Ansvisor turns on Product Visibility for the brand and says so on this step. You can turn it off in brand settings.</Step><Step title="6. What do you work on? (cloud only)">Pick what you work on or lead (Founders & leaders, Brand & PR, Content, Growth and more), and your left menu keeps only the sections you need. **Skip: show me everything** keeps every section, and you can change it later in **Settings → Account**. Self-hosted instances ask the same the first time you open the dashboard. See [Menu access](/guides/menu-access).</Step><Step title="7. Plan & checkout (cloud only)">- On the cloud, the final step picks your subscription plan (Starter, Growth, or Enterprise) and runs Stripe Checkout. All paid plans include a **14-day free trial** — you enter card details but no charge happens until day 15. Self-hosted instances skip this step entirely.+ On the cloud, the final step picks your plan, **Starter** or **Growth**, and runs Stripe Checkout. While a free trial is on offer, **Choose how to start** offers a **14-day trial**, **Monthly** or **Yearly**. With the trial, the plan's button reads **Start 14-day free trial**: you enter card details, nothing is charged until the trial ends, and the step tells you the day of the first charge. Otherwise it reads **Buy now**. The trial comes with an organization's first subscription only; without it, the plan starts the same day. Self-hosted instances skip this step entirely.</Step></Steps>+To add another brand later, pick **Add Brand** in the brand switcher. It walks through the same first five steps; your plan sets how many brands you can have.+## What happens after you finish-The first round of AI engine queries kicks off automatically and finishes in 5–15 minutes (depending on prompt count and plan). The dashboard updates live as platforms report back. While you wait:+The first round of AI engine queries starts automatically: right away on self-hosted instances, after checkout on the cloud, and the dashboard opens. The first run can take anywhere from a few minutes to 1–2 hours at busy times. While you wait:-- **Insights** — first KPI cards appear within 1–2 minutes of the run starting-- **Citations** — populates as AI responses come back with source URLs-- **Prompts → Insights tab** — Suggestions card refreshes after the run, surfacing new prompts to add+- **Brand Visibility** — shows that the first tracking is in progress, and fills in with your results. You can leave the page; the run keeps going in the background.+- **Citations** — fills in with the source URLs AI answers cite+- **Prompts → Prompt Suggestions** — prompt ideas to add to tracking## Adding the tracking pixel (optional, post-onboarding)The onboarding flow doesn't include the tracking pixel — it's an opt-in step you do separately for **AI Traffic Analytics** (real visits arriving from AI answer engines). To set it up:<Steps>- <Step title="Open the Traffic page">- Navigate to `/dashboard/traffic` after onboarding. The snippet is shown at- the top of the page.+ <Step title="Open the AI Referral Traffic page">+ Pick **AI Referral Traffic** in the sidebar (`/dashboard/traffic`) after onboarding. Until the snippet sends its first visit, the code is shown at the top of the page; after that, **Code** on the **Tracking snippet** card shows it again.</Step><Step title="Copy the snippet">Looks something like:@@ -105,7 +110,7 @@ The onboarding flow doesn't include the tracking pixel — it's an opt-in step y</Step></Steps>-Visits start logging immediately; the dashboard updates near-realtime.+Once the snippet sends a visit, the **Tracking snippet** card shows it as active with the time of the last visit. See [AI Traffic Analytics](/guides/ai-traffic-analytics) for the rest of the page.## Common pitfalls@@ -117,7 +122,7 @@ Visits start logging immediately; the dashboard updates near-realtime.stays at 0 when both are missing — which is exactly what AEO is for.</Accordion><Accordion title="Prompts include my brand name — should I remove?">- Yes. *"What is Linear?"* style prompts almost always score 100 (the AI+ Yes. *"What is Acme?"* style prompts almost always score 100 (the AIobviously talks about you when asked) but they're not measuring organicdiscovery. Remove brand-name prompts; they distort averages.</Accordion>@@ -128,13 +133,15 @@ Visits start logging immediately; the dashboard updates near-realtime.</Accordion><Accordion title="Why is Google AI Overviews missing from my plan?">Starter plan runs only ChatGPT and Microsoft Copilot. Google AI Overviews,- Google AI Mode, Gemini, Perplexity, Grok, and Claude unlock on Growth and- Enterprise plans (cloud), or are all available immediately on self-hosted.+ Google AI Mode, Gemini, Perplexity and Grok unlock on Growth and Enterprise+ plans (cloud), or are all available immediately on self-hosted. Claude runs+ on self-hosted, and is an Enterprise option on the cloud.</Accordion><Accordion title="Can I add more topics later?">- Yes. From the **Topics** page or the **Suggestions** card in **Prompts →- Insights**, you can add new topics and prompts at any time. Tracking- immediately picks them up on the next scheduled run.+ Yes. On **Prompts → Topics**, admins and managers can add topics with **Add+ Topic** or from the **Topic Suggestions** card, and **Prompts → Prompt+ Suggestions** offers new prompts to track. New prompts run with the next+ daily run.</Accordion></AccordionGroup>diff --git a/docs/guides/answer-engine-insights.mdx b/docs/guides/answer-engine-insights.mdxindex f02aa77ac..8ed2a8ca0 100644--- a/docs/guides/answer-engine-insights.mdx+++ b/docs/guides/answer-engine-insights.mdx@@ -1,40 +1,73 @@---title: "Answer Engine Insights"-description: "The Insights page is your daily AEO command center."+description: "Brand Visibility is your daily view of how AI answers treat your brand."---## What you see-The **Insights** page (`/dashboard/insights`, **Brand Visibility** in the sidebar) is the main analytics hub for a brand. It breaks down your AI visibility across four panels:+**Brand Visibility** in the sidebar opens the **Answer Engine Insights** page (`/dashboard/insights`), the main analytics hub for a brand. From top to bottom:<Steps>- <Step title="KPI strip (top)">- Brand-level visibility score, mention count, citation count, and active prompt count — each with a 7-day delta against the prior week.+ <Step title="Header">+ The brand's name, when the last run finished and when the next one is due. **Formulas** explains how every number on the page is calculated, **Export CSV** downloads the answers behind the page with the current filters (up to 50,000 rows), and **Reports** opens Reports. Self-hosted instances also have **Test Single Prompt** and **Run All** to start a run by hand.</Step>- <Step title="Trend chart">- A 30-day line chart of visibility per platform. Spot platform-specific dips (e.g. Perplexity dropped while ChatGPT held) and correlate with content publication or competitor activity.+ <Step title="Summary line">+ One line with your Visibility score and its change, your rank and the gap to the brand next to you, and the platforms that moved most. The copy button puts the line on your clipboard.</Step>- <Step title="Platform breakdown">- Stacked bars showing which AI engines drive the most/fewest mentions for your brand. Useful for routing content investment toward your weakest platform.+ <Step title="Key metrics">+ Nine cards. Most show their change **vs previous period** and a small daily line:++ - **Visibility** — your score from 0 to 100, and your rank among the tracked brands. Click it to open the breakdown panel.+ - **Tracked prompts** — prompts answered in the period. On plans with a limit, a bar shows how many prompt locations your workspace uses. Click it to open Prompts.+ - **Mentions** and **Citations** — how often answers named your brand and cited your pages. They open the Mentions and Citations pages.+ - **Net sentiment** — the positive minus the negative share of the answers that name you. It opens Mentions.+ - **Coverage** — the share of answered prompts where you appear at least once.+ - **Share of voice** — your mentions out of all mentions of tracked brands.+ - **Avg. position** — where you're named in the answers that name you. Lower is better.+ - **Citation rate** — the share of answers that cite your domain.++ A rate based on fewer than 20 answers says **Low sample** and shows no change.</Step>- <Step title="Drill-down sheet">- Click any prompt or platform cell to open a side sheet with the actual AI responses, citations, and competitor mentions for that cell.+ <Step title="Visibility trend and Leaderboard">+ Shown once you track competitors; until then, a card links you to adding them. The trend draws your Visibility over the range next to your competitors' lines. Admins and managers can **Pin** up to 5 competitors to keep on the chart; without pins, the strongest four are shown. Outside the 24-hour view, it also marks the days prompts were added and your Action Center goal for AI visibility, if one is set.++ The **Leaderboard** ranks you against your competitors, with each brand's score, change, Coverage and share of voice. Under your row it shows the gap to the brand ahead and the platform where that brand leads you most. **Head-to-Head** opens Competitors.++ </Step>+ <Step title="By AI platform">+ A table with each platform's Visibility, Change, Coverage, Share of voice and Avg. pos. The row with the biggest drop is highlighted. A platform with too few answers shows **Low sample** or **No runs this period** instead of numbers.+ </Step>+ <Step title="Why it changed">+ The platforms, topics and prompts that moved your Visibility most, under **Gains** and **Drops**, each with its own score before → after and its effect on your overall score. A note counts the prompts added during the period, which aren't counted in the change. Click a row, or **Full breakdown**, to open the breakdown panel.+ </Step>+ <Step title="Topics vs competitors">+ One row per topic, with your score and the score of each competitor on the trend, shaded from low to high. The last column shows the gap to the topic's leader, or **Lead** when you lead. Click a topic to open its page.+ </Step>+ <Step title="Opportunities">+ What to track next, from your prompt suggestions. A topic has **Track N**, which tracks all its suggested prompts, and **Send action**, which opens a Growth action in the Action Center. A prompt has **Track** and **Suggest content**, which writes a content suggestion for its topic from your monthly content allowance. Tracking stops when your plan's prompt locations are full. **Track** and **Suggest content** are for admins and managers. **See all** opens **Prompts → Prompt Suggestions**.+ </Step>+ <Step title="Breakdown panel">+ The Visibility card, a **Why it changed** row and **Full breakdown** open the **Visibility Breakdown** panel. It compares the selected range with the period of the same length just before it, names the prompt and platform behind the biggest gain or drop, and lists every slice under **Prompts**, **Platforms** and **Topics**. Click a prompt to open its page, where **Platform Results** shows each AI answer and the sources it cited.</Step></Steps>## Reading the visibility number+Visibility is a score from 0 to 100, not a percentage. It blends how often AI answers mention your brand, how often they cite your site and how early they name you. Every answer counts, including the ones that leave you out. **Formulas** shows the exact formula. Competitors are scored the same way over the same answers, so their numbers are directly comparable.+A few quick interpretations to anchor you:-- **Under 15%** — Cold start. Brand barely known to AI engines on these prompts.-- **15–35%** — Emerging presence. AI sometimes cites you but competitors dominate.-- **35–60%** — Established. You're reliably cited; focus on the 1–2 platforms or topics still trailing.-- **Over 60%** — Category leader. Your job is now defending the moat against new entrants.+- **Under 15** — Cold start. Brand barely known to AI engines on these prompts.+- **15–35** — Emerging presence. AI sometimes mentions you but competitors dominate.+- **35–60** — Established. You're reliably mentioned; focus on the 1–2 platforms or topics still trailing.+- **Over 60** — Category leader. Your job is now defending the moat against new entrants.++The exact threshold depends heavily on category competitiveness. *"longest range luxury EV"* might have a clear winner at 40, while *"best CRM for small business"* is so saturated that 20 is leadership.-The exact threshold depends heavily on category competitiveness. *"longest range luxury EV"* might have a clear winner at 40%, while *"best CRM for small business"* is so saturated that 20% is leadership.+Every change compares the selected range with the period of the same length just before it, over only the prompts answered in both periods, so adding prompts doesn't inflate it. Visibility changes are in points; Mentions and Citations change in percent. With **All** selected there is no earlier period, so no change is shown.<Tip>-**Don't fixate on the absolute number — fixate on the delta.** A brand growing from 18% → 24% in a quarter is healthier than a stagnant 50%.+**Don't fixate on the absolute number — fixate on the change.** A brand growing from 18 → 24 in a quarter is healthier than a stagnant 50.</Tip>## Common workflows@@ -42,17 +75,17 @@ The exact threshold depends heavily on category competitiveness. *"longest range### Weekly review (10 min)<Steps>- <Step title="Check brand-level delta">- Up or down? If down ≥10%, dig into the trend chart to find when the drop happened.+ <Step title="Check the Visibility change">+ Set the range to **7d**. Up or down? If down, **Why it changed** shows which platforms, topics and prompts moved it.</Step><Step title="Identify the trailing platform">- Pick the platform contributing least; that's your next investment.+ In **By AI platform**, find the platform with the lowest score or the highlighted biggest drop; that's your next investment.</Step>- <Step title="Skim Suggestions">- Look at AI-suggested new prompts and topics gap is widening; queue 1-3 to add.+ <Step title="Skim Opportunities">+ Look at the suggested topics and prompts; track 1–3 of them.</Step><Step title="Send 1 brief to writers">- From Content Optimization, generate a brief for the worst-performing prompt this week.+ From **Content → Opportunities**, generate a brief for the worst-performing prompt this week.</Step></Steps>@@ -61,14 +94,17 @@ The exact threshold depends heavily on category competitiveness. *"longest rangeWhen a metric drops dramatically:<Steps>- <Step title="Open the drill-down on the dropped cell">- Side sheet shows the actual AI response. Read it: is your brand still mentioned but ranked lower? Or completely absent?+ <Step title="Open the breakdown">+ Click the Visibility card, or the dropped row in **Why it changed**. The panel names the prompt and platform behind the biggest drop.</Step>- <Step title="Inspect competitor mentions">- The drill-down lists every competitor cited in that response. New competitor surge is often the cause.+ <Step title="Read the answers">+ Click the prompt to open its page and read the answers under **Platform Results**. Is your brand still mentioned but named later? Or completely absent?</Step>- <Step title="Check citation diff">- Compare citation URLs from this run vs. last week. A retracted article or a new competitor blog post is often the trigger.+ <Step title="Check the competition">+ The **Leaderboard** and **Topics vs competitors** show who leads where. A competitor surge is often the cause; **Head-to-Head** opens Competitors for a closer look.+ </Step>+ <Step title="Check the sources">+ Each answer lists the sources it cited, and the **Citations** card opens the Citations page. A retracted article or a new competitor blog post is often the trigger.</Step><Step title="Decide remediation">Either: ship a content piece targeting the prompt (Content Optimization), or earn a placement (PR), or accept it as a one-time blip.@@ -77,13 +113,14 @@ When a metric drops dramatically:## Filters and date range-Top-right of the page:-- **Platform** — restrict to a single AI engine-- **Region** — filter by user region (if your prompts run in multiple)-- **Topic** — narrow to one topic cluster-- **Date range** — 7d / 30d / 90d / custom+Under the header:++- **Date Range** — **24h** (the default: the latest completed run), **7d**, **30d**, **90d**, **All** or **Custom**+- **Topic** — narrow to one topic (shown when the brand has topics)+- **Region** — narrow to one region your prompts run in+- **AI Model** — narrow to one AI platform; versions of the same engine count as one-Filters apply to all four panels simultaneously.+Filters apply to everything on the page except **Opportunities**, which lists your stored suggestions. They're kept in the page's address, so a link you share opens with the same filters.<Card title="Continue: Topics" icon="arrow-right" href="/guides/topics">Drill into topic clusters to find which themes you own and which you're losing.diff --git a/docs/guides/citations.mdx b/docs/guides/citations.mdxindex 2ac6b66bc..87d88b34e 100644--- a/docs/guides/citations.mdx+++ b/docs/guides/citations.mdx@@ -1,49 +1,141 @@---title: "Citations"-description: "Every URL AI engines cite alongside your brand, classified by source type."+description: "The domains and URLs AI engines cite when they answer your tracked prompts, by source type."---## What it shows-The **Citations** page (`/dashboard/citations`) aggregates every URL that AI engines cited across your tracked prompts. Each row shows:+The **Citations** page (`/dashboard/citations`) lists the domains and URLs that AI engines cited in their answers to your tracked prompts, for the active brand in the sidebar. It reads the answers your tracking already stores.-- The URL and its domain-- **Source type** classification (news, review, owned, social, forum, listicle, vendor)-- Number of times it was cited in the last 30 days-- Which prompts triggered it-- Whether your brand was mentioned in that citation's content+## Filters++| Filter | What it does |+|---|---|+| **Date Range** | 24h (the default), 7d, 30d, 90d, All or Custom |+| **Topic** | One topic. Shown only when the brand has topics. |+| **Prompt** | One tracked prompt; type to search the list |+| **Platform** | One AI platform, or all of them |+| **Region** | One region the answers were tracked in, or all of them |++The filters live in the URL, so a refresh or a shared link opens the same view. When a table is empty for the window but the brand has citations outside it, **Show all data** clears the filters and shows all dates and all sources.++## Summary cards++- **Total Citations** — every citation in the window, and how many tracked results (AI answers) they come from+- **Unique Domains** — the cited domains in the source choice below (**Brand**, **Competitors**, **Third-Party** or **All**), with their unique URLs+- **Avg citations per result** — the number of links per AI answer++## Top Sources++The **Top Sources** card has four tabs: **Domains**, **URLs**, **Competitor Gaps** and **Source Types**.++Above the Domains and URLs tables, four buttons choose which sources they list:++- **Brand** (the default) — your brand's own domains+- **Competitors** — the domains of the competitors you track+- **Third-Party** — every other site+- **All** — every source++The choice doesn't change **Total Citations**, **Avg citations per result**, Competitor Gaps or Source Types.++### Domains++Each cited domain, ranked by how often it was cited:++| Column | What it shows |+|---|---|+| **Domain** | The domain, its source type, and a link that opens the site |+| **Platforms** | The AI platforms whose answers cited it |+| **Usage** | The share of tracked answers in the window that cite it |+| **Avg Citations** | How many times an answer that cites the domain cites it, on average |++On a domain that isn't yours or a tracked competitor's, the **+** button (**Add as competitor**) opens a dialog with a name taken from the domain. Edit the name and click **Add** to track it on [Competitors](/guides/competitors).++### URLs++Each cited page, ranked by its citations, with **Platforms**, **Usage** and **Citations**. Click a page's title to open its [URL page](#the-url-page); the small icon beside it opens the page itself. The tab lists up to the 2,000 most-cited URLs, and its count is the full number.++Both tables show 100 rows a page.++### Export++**Export CSV** in the header downloads the open tab under the filters:++- **Domains** — `domain`, `category`, `total_citations`, `results_citing`, `usage_pct`, `models`+- **URLs** — `url`, `domain`, `category`, `title`, `total_citations`, `results_citing`, `usage_pct`+- **Competitor Gaps** — the gap list: `domain`, `category`, `competitor_answers`, `competitors`, `strength`++Source Types has no export.## Source classification-Ansvisor automatically classifies citations into seven categories:+Ansvisor gives every cited domain one of eight types:++| Type | What it covers |+|---|---|+| **You** | Your brand's domains and their subdomains |+| **Competitor** | The domains of the competitors you track, and their subdomains |+| **Editorial** | A fixed list of well-known news, tech and magazine sites |+| **Forum** | Forums and question-and-answer sites |+| **Social** | Social networks, video sites and blogging platforms |+| **Review** | Review and rating sites |+| **Institutional** | `.edu`, `.gov` and `.mil` addresses (country versions included), and a list of public and international bodies |+| **Other** | Every site that isn't on one of the lists |-| Type | Examples | Why it matters |-|---|---|---|-| **Owned** | your-domain.com, blog.your-domain.com | Pages you control — the easiest to optimize |-| **News** | TechCrunch, The Verge, Bloomberg | High-trust signal; one good placement = months of AEO impact |-| **Review** | G2, Capterra, TrustPilot, Wirecutter | AI engines weight these heavily for buying-intent prompts |-| **Listicle** | "Best 10 X" articles | Easy citation pickups via outreach |-| **Forum** | Reddit, Hacker News, Quora | Surprisingly influential for technical/B2B queries |-| **Social** | Twitter, LinkedIn | Lowest weight in current LLMs |-| **Vendor** | direct competitor sites | Indicates you're losing comparison ground |+**You** and **Competitor** come first: a tracked competitor's domain is always **Competitor**, even when it's also a review site. Only competitors with a domain are matched. The other lists are short, so most sites are **Other**.++The **Source Types** tab shows the cited domains in a donut chart, with each type's share of the domains (not of the citations). It covers every cited domain in the window, whatever the source choice.## How to use it-### Find your earned-media wins-Sort by `times cited` descending → filter by `source type: news, review, listicle`. Anything in the top 20 is doing meaningful AEO work for you.+### See which of your pages AI cites+On the **Brand** choice (the default), the URLs tab lists your own pages that AI cites, on which platforms and how often. Open a page to see the prompts it's cited for.++### Find the third-party sources AI trusts+Choose **Third-Party**. The top of the Domains and URLs lists are the sites AI leans on most for your prompts: places to be mentioned or cited.++### Find outreach targets in Competitor Gaps+**Competitor Gaps** lists third-party domains that AI cites when it names a competitor and not you. It has two views:++- **Gap list** — domains cited in at least two answers that name a competitor while your brand isn't named and none of your domains is cited, and never cited in an answer where you appear. Columns: **Domain**, **Source type**, **Competitor answers**, **Which competitors** and **Strength**. Up to 100 domains, strongest first.+- **By competitor** — pick a competitor to see the third-party domains cited in answers that name it, with **Answers feeding**, **Also cites us?** (whether the domain also appears in an answer where you appear) and **Strength**.++**Strength** weighs each answer by how many sources it had, so a source in a two-source answer counts more than one in a twenty-source answer (**How this works**). When your brand appears in fewer than one answer in ten in the window, a note says the list may be broad: work on your baseline visibility first.++Competitor Gaps follows the date, topic, prompt, platform and region filters, not the **Brand** / **Competitors** / **Third-Party** / **All** choice.++### Watch your competitors' pages+Choose **Competitors** to see which competitor domains and pages AI cites in your answers.++## The URL page++Click a page's title on the URLs tab to open its page (`/dashboard/citations/url`). It opens with the Citations page's date range, platform and region (not its topic or prompt), and you can change the date range and platform there. **Citations** at the top goes back.++The header shows the page's title and address, its source type and, when Ansvisor can tell from the address and title, its article type: **Topic Guide**, **How-to Guide**, **Review**, **Ranked List** or **Comparison**. Your own pages are marked **Owned**; any other page has **Add as competitor**, which adds its domain.++Five cards sum it up: **Total citations**, **Answers citing**, **Prompts**, **Platforms** and **Last seen** (with the date it was first seen).++For your own pages, two more cards:++- **Targeted in N prompts** — the prompts that list this page in their **Target URLs**, and how many times it was cited for each+- **AI-referred visits** — visits to this page from AI platforms in the window, by platform++### Cited in-### Find your defensive gaps-Filter by `source type: vendor` → these are competitor pages that AI engines cite when answering questions in your category. Each one is an opportunity for a counter-piece.+Every AI answer in the window that cites the page, newest first, 10 a page:-### Identify outreach targets-Filter by `source type: review, listicle` → look for high-traffic articles where your brand is **not** mentioned. Those are direct outreach targets — ask for inclusion.+| Column | What it shows |+|---|---|+| **Date** | When the answer was tracked |+| **Platform** | The AI platform that gave the answer |+| **Prompt** | The prompt; click it to open the prompt's page |+| **Sentiment** | The answer's sentiment |+| **Brand mentioned** | A check when the AI answer names your brand. It says nothing about the cited page's own text. |+| **Position** | Where the page's first citation sits among the answer's citations: **Early**, **Mid** or **Late**, with its number, e.g. *#2 of 7* |-## Drill-down+### Prompts breakdown-Click any citation row to see:-- Which exact AI responses cited it-- The prompt that triggered each citation-- Whether your brand was named in the cited page's content+The prompts whose answers cite the page, with **Answers**, **Citations** and **Last seen**, most citations first.<Card title="Continue: AI Traffic Analytics" icon="arrow-right" href="/guides/ai-traffic-analytics">Measure real visits arriving on your site from AI answer engines.diff --git a/docs/guides/competitors.mdx b/docs/guides/competitors.mdxindex 837bcc72c..44cb2fe04 100644--- a/docs/guides/competitors.mdx+++ b/docs/guides/competitors.mdx@@ -1,39 +1,65 @@---title: "Competitors"-description: "Track named competitors and benchmark visibility side-by-side."+description: "Track named competitors and compare your AI visibility with each one, head-to-head."---+## Opening the page++The **Competitors** page (`/dashboard/competitors`) isn't on the left menu. Open it from [Brand Visibility](/guides/answer-engine-insights): **Head-to-Head** on the **Leaderboard** card, or a competitor's name there, which opens the page with that competitor selected. Before a brand has competitors, Brand Visibility shows **Head-to-Head Comparison** in the leaderboard's place. The Action Center's **Add at least 3 competitors** step in Getting started opens it too.+## Adding competitors-On the **Competitors** page (`/dashboard/competitors`) click `+ Add competitor`. Each competitor has:+Click **Add Competitor**. Each competitor has:++- **Name** — as AI answers write it. Ansvisor looks for the name in every answer.+- **Domain** (optional) — Ansvisor also looks for the domain in answers, counts citations of the competitor's pages, marks those pages **Competitor** on [Citations](/guides/citations), and lets the timeline card below follow them.++**Suggest competitors** researches your brand on the web, from its website, region and language, and lists competitors with their domains. The ones you already track are left out. All of them are ticked: untick the ones you don't want and click **Add N competitors**. **Refresh suggestions** asks again. The brand needs a website first.++On [Citations](/guides/citations), the **+** on a cited domain adds that site as a competitor.-- **Name** — exactly as it appears in AI responses (e.g. *Salesforce*, not *salesforce.com*)-- **Domain** (optional) — used for citation cross-checks+The Getting started step asks for at least 3 competitors, and 5–20 give the clearest picture. A competitor is counted in the answers tracked after you add it; earlier answers aren't counted again.-Aim for 3–8 competitors. Fewer than 3 and benchmarks have no signal; more than 8 and the comparison view gets noisy.+To remove a competitor, hover its card, click the bin icon, then **Yes, remove competitor**. It's no longer tracked. Past results keep their numbers, but they can't be linked back to the competitor.++On Ansvisor Cloud, while the workspace is [read-only](/faq), **Add Competitor**, **Suggest competitors** and removing a competitor open the plan dialog instead.## What the page shows-For each competitor:-- Mention frequency across your tracked prompts (last 7 days, last 30 days)-- Visibility share vs. yours-- Top 3 prompts where the competitor leads-- Trend delta — is the competitor gaining ground or losing it?+The **Tracked Competitors** card lists every competitor with its domain and:++- its **AI Visibility Score** (0–100), the score on the Brand Visibility leaderboard, from how often answers name it, cite its site and how early it's named. Hover the score for its answers, citations and position factor.+- the prompts it's visible in, out of the prompts with answers in the window, e.g. *12/40 prompts*++**No data** means no answer in the window was measured for that competitor yet, for example one you've just added. The **Date Range** at the top (7d, 30d by default, 90d, All or Custom) sets the window for these scores.++**Export CSV** on the card downloads your brand's and every competitor's scores: `name`, `is_own_brand`, `visibility_score`, `visible_prompts`, `prompt_count`, `mention_answers`, `citation_answers`, `mentions`, `citations`.## Comparison views+Click a competitor's card to compare it with your brand under **[Your brand] vs [competitor]**; click it again to close the comparison. The selected competitor is kept in the URL (`?competitor=`), so a refresh or a shared link opens the same one.++The comparison reads every tracked answer, not just the date range. Its scores are each answer's visibility score (0–100), for your brand and for the competitor.+<Steps>- <Step title="Side-by-side per prompt">- Drill into any prompt: shows your visibility vs. each competitor on that single prompt across all platforms.+ <Step title="Your Avg. Score, Their Avg. Score, Score Difference">+ Your average score, the competitor's, and the difference between them.</Step>- <Step title="Topic-level competitive map">- Each topic shows which competitor leads, the gap percentage, and how the gap has moved week-over-week.+ <Step title="Platform Breakdown">+ Your average and the competitor's on each AI platform, with the difference. A competitor can lead on one platform and trail on another.</Step>- <Step title="Platform skew">- Some competitors might dominate Perplexity but underperform on ChatGPT (or vice-versa). The platform skew chart highlights these for targeted optimization.+ <Step title="Gaps and Strengths">+ **Gaps** lists up to 10 prompt and platform combinations where the competitor scores higher, grouped by prompt, the widest gap first. **Strengths** lists up to 10 where you score higher, your biggest lead first. A prompt with several platforms opens to show each one.+ </Step>+ <Step title="Prompt-by-Prompt Comparison">+ Every prompt with **You**, **Them** and **Diff**, the most recently run first. Click a prompt to see each platform (with its model and region) and how many runs it has. Click a platform with more than one run to see its **Previous runs**, up to 50, with the date, both scores, the difference and the sentiment. The eye icon opens an AI answer.</Step></Steps>+**Export CSV** beside the comparison's title downloads it per prompt and platform: `prompt`, `platform`, `model`, `region`, `runs`, `brand_score`, `competitor_score`, `difference`, `latest_at`.++When there's nothing to compare yet, the comparison says **No comparison data**: run tracking for your prompts first.+## A competitor's pages over timeBelow a competitor's comparison, a card shows the competitor's pages over time: why it may be rising. A chart shows the answers that mentioned the competitor, and your brand, each week for the last twelve weeks. A marker sits on each week something happened to the competitor's pages, and a list below names those events, newest first:@@ -41,25 +67,17 @@ Below a competitor's comparison, a card shows the competitor's pages over time:- **First cited in your tracked answers**: the first day an AI answer to one of your prompts cited one of the competitor's pages. When a competitor is added, Ansvisor reads back 90 days of your answers once, so the first date is the first within that window.- **Changed**: once a week, Ansvisor reads again the 10 competitor pages your answers cited most over the last two weeks. When a page's words changed by more than a date or a price moving, it says so, with the Site Audit checks the page gained (an FAQ, a table, statistics…) or lost.-Pages are read for free from their public address, never from a site whose robots.txt keeps crawlers out. These reads share a brand's 12 page reads a day with the Action Center's tasks, which go first. Only what Site Audit's checks found and a summary of the page's words are kept, never its text. Nothing is compared with another brand's answers.--## Auto-discovered competitors--Even if you don't add competitors manually, AI responses **mention** other brands when answering your prompts. The Insights drill-down sheet exposes these — recurring names you didn't add are strong candidates for the competitors list.--<Tip>-**Workflow tip**: monthly, review the auto-discovered names. If a brand you've never heard of is being cited 3+ times across your prompts, add it to your list. They're a stealth competitor that AI engines already know about.-</Tip>+The card needs the competitor's domain to find its pages. Pages are read for free from their public address, never from a site whose robots.txt keeps crawlers out. These reads share a brand's 12 page reads a day with the Action Center's tasks, which go first. Only what Site Audit's checks found and a summary of the page's words are kept, never its text. Nothing is compared with another brand's answers.## Closing visibility gapsOnce a gap is visible, the workflow is:-1. Identify the prompt(s) where the competitor leads most-2. Inspect the AI response — what content/citation is the competitor winning with?-3. Generate a content brief targeting that prompt (Content Optimization)-4. Ship the piece, earn placements, monitor 2–4 weeks for the gap to close+1. On **Gaps**, find the prompts where the competitor leads most+2. Open the AI answer with the eye icon: what is the competitor named or cited for? The timeline card shows whether its pages changed, and **Competitor Gaps** on [Citations](/guides/citations) lists the sources AI cites with the competitor and not with you+3. Create content for that prompt in **Content** (see [Content Optimization](/guides/content-optimization))+4. Publish it, earn placements on those sources, and watch the prompt in the comparison as new answers are tracked<Card title="Continue: Content Optimization" icon="arrow-right" href="/guides/content-optimization">- Generate AI content briefs to systematically close visibility gaps.+ Turn visibility gaps into content from Content › Opportunities.</Card>diff --git a/docs/guides/content-editor.mdx b/docs/guides/content-editor.mdxindex f1806193e..862c05e43 100644--- a/docs/guides/content-editor.mdx+++ b/docs/guides/content-editor.mdx@@ -7,9 +7,9 @@ description: "Plan what to write next, start a page yourself or with the Content**Content** in the sidebar has four pages:-- **Plan** (`/dashboard/content/plan`): what to create, optimize or protect next, ranked.-- **Editor** (`/dashboard/content/editor`): back to the draft you last opened in the editor for this brand, in this browser. With none, or if that draft was deleted, it opens **New content** to start a page.- **Opportunities** (`/dashboard/content`): the content opportunities Ansvisor finds in your visibility gaps. See [Content Optimization](/guides/content-optimization).+- **Plan** (`/dashboard/content/plan`): what to create, optimize or protect next, ranked.+- **Editor** (`/dashboard/content/editor`): back to the draft you last opened in the editor for this brand, in this browser. With none, or if that draft was deleted or archived, it opens **New content** to start a page.- **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**.@@ -128,28 +128,30 @@ If the agent can't start, for example because this month's AI usage is spent or## 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 header shows the title (click it to rename it in the page) and whether your changes are saved. Under them come the page type, the method and status, a **Rules** chip with how many rules the page meets now (click it to open the rules), and, on a page that optimizes a live one, how many cited passages are kept. The page saves as you write. On the right are the month's AI usage and the buttons **History**, **Copy HTML**, **Export**, **Send to CMS** (the paper-plane icon, admins and managers) 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.-Words in square brackets, such as `[figure, source]` or `[competitor]`, are placeholders: the Content Agent leaves one where a real name, quote or number goes. Each is tinted amber in the page, and the toolbar counts those left to fill. Click the count or the arrows beside it to go to the next or the previous one, already selected, so you type over it. A placeholder in an image's alt text, the JSON-LD or an HTML block isn't in the page's text: it's counted too, and **Show in HTML** selects it in the HTML view. Export and Send to CMS wait until none is left.+Words in square brackets, such as `[figure, source]` or `[competitor]`, are placeholders: the Content Agent leaves one where a real name, quote or number goes. Each is tinted amber in the page, and the toolbar counts those left to fill. Click the count or the arrows beside it to go to the next or the previous one, already selected, so you type over it. A placeholder in an image's alt text, the JSON-LD or an HTML block isn't in the page's text: it's counted too, and **Show in HTML** selects it in the HTML view. Send to CMS waits until none is left. With [Quality](#quality) on, Export asks first: **Fill now**, or **Export without them**, which leaves the sentences with a placeholder out (one in the title or a heading has to be filled).### Side panel-The panel opens on **Rules**. Its tabs are **Rules · Brief · Sources · Live page**.+The panel's tabs are **Instructions · Sources · Live page**. **Instructions** holds what the Content Agent follows: **Brief** and **Rules**, and **Quality** when it's on, switched at its top. The panel opens on **Instructions**, on **Rules**. While the panel is closed, its tabs run down the editor's right edge: click one to open the panel there.-- **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). It also reads a few of the pages AI cited for them: their typical length shows beside **Length**, and **Cited pages have** lists what Site Audit's checks find on at least half of them (an FAQ schema, tables, statistics…). The Content Agent then writes the page toward what its text can carry (tables, statistics, quotes…), not its schema, dates or byline, which your site sets. **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.+- **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** (admins and managers) 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. **Run Agent** sits at the top: see [Run Agent](#run-agent).+- **Brief**: the page type, target URL, goal, audience, length, outline and keywords. **Edit brief** to change it. With no brief yet, **Run Agent** writes the goal, audience and outline from your sources; once there is one, the button reads **Rebuild brief**. Either writes the outline from the sources you keep, each H2 answering a search AI ran for your prompts (a fan-out). If you edited the brief, rebuilding asks first: **Rebuild anyway** or **Keep my brief**. A draft started from an opportunity with a brief starts with that brief's outline and keywords. Building the brief also reads a few of the pages AI cited: their typical length shows beside **Length**, and **Cited pages have** lists what Site Audit's checks find on at least half of them (an FAQ schema, tables, statistics…). The Content Agent then writes the page toward what its text can carry (tables, statistics, quotes…), not its schema, dates or byline, which your site sets. Once the brief has an outline, **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.+- **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. **Results from AI visits** shows the AI visits that landed on the page and, with Google Analytics connected, their key events, orders and revenue, by AI source. **Your other pages for these prompts** lists your other pages cited for the same prompts. A new page has nothing to measure until it's marked published with its live address.On the **Live page** tab, **Conversions from AI journeys** shows what the journeys through the page brought in, from [conversions from AI visits](/guides/ai-traffic-analytics#conversions-from-ai-visits). A conversion counts when its journey landed on the page, went through it or ended on it, credited to the AI assistant of its first visit. The cards follow your brand's **Site type**: signups and demo forms for B2B SaaS; orders, revenue and units sold for e-commerce; bookings, revenue and newsletter signups for B2C; then any other goal reached. Under them come the conversions per AI source and the **Top journeys**, with the page marked **This page** (a long journey is shortened, with this page kept in view). The journeys are the latest 2,000 conversions', each with its latest 100 pages; the counts take every conversion. While conversions are off, the section says where to turn them on, and keeps showing what was counted before.-Rebuilding the outline and running the Content Agent use your workspace's monthly AI usage.+Building the brief and running the Content Agent use your workspace's monthly AI usage.++### Run Agent-### Apply rules with Agent+**Run Agent**, at the top of **Rules**, asks the Content Agent to suggest small, reviewable changes for the rules the page doesn't meet yet (**Fix open rules**). Its **▾** menu also offers **Rewrite the whole page**: one new version written to every rule in the set, with the cited passages kept, which uses more AI usage. The menu marks it **Recommended** when the page is far off its Length or many rules are open; pick it, and the button reads **Rewrite page**. A rewrite comes back as one change: **Compare** it with your page, then **Accept** or **Reject**; your page before it stays in History. It isn't offered once the page is ready or published.-**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**. What you accept and reject teaches it: for a rule whose suggestions this brand has mostly rejected over the last 90 days (at least five decided, on two pages or more, seven in ten rejected), it keeps its changes as small as the rule allows, and while it works its card says which rules. Only its small changes count: a rejected **Rewrite the whole page** doesn't. On a draft that optimizes a live page, it is also told how that page does now, as the **Live page** tab shows it over 30 days: how often AI answers cite it and the prompts it lost. It keeps the answers and facts AI engines cite, answers a lost prompt's question where a rule's change can, and its card says what it kept in mind. Quality's **Hand off** isn't affected.+The small changes appear in the page, each with **Accept** and **Reject**, under a bar with **Accept all** and **Reject all**. What you accept and reject teaches it: for a rule whose suggestions this brand has mostly rejected over the last 90 days (at least five decided, on two pages or more, seven in ten rejected), it keeps its changes as small as the rule allows, and while it works its card says which rules. Only its small changes count: a rejected **Rewrite the whole page** doesn't. On a draft that optimizes a live page, it is also told how that page does now, as the **Live page** tab shows it over 30 days: how often AI answers cite it and the prompts it lost. It keeps the answers and facts AI engines cite, answers a lost prompt's question where a rule's change can, and its card says what it kept in mind. Quality's **Hand off** isn't affected.- 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.@@ -163,15 +165,31 @@ When a draft optimizes a live page, brought in by its URL, the passages AI answeThe 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.+### Quality++Quality is turned on per installation; where it's off, what this section describes doesn't show. With it on, **Instructions** has a third segment, **Quality**, and the header a **Quality** chip with the page's score.++Quality scores the page from 0 to 100 on **E-E-A-T**, **Trust** and **Readability**: 80 and up is **Strong**, 60 to 79 **Can improve**, under 60 **Needs work**. The scores are Ansvisor's estimates from Google's published quality signals, not a Google score. At the bottom, **Site trust** (out of 5) comes from Site Audit's checks of your site, with **Fix in Site Audit** when some are missing.++- **Your to-dos** are what only you can do: pick the page's author, add your own experience or data, link the proof for a claim, fill the placeholders.+- **What would raise it** lists the checks still open, each with the points it would add to a score and, where it has one, a button such as **Show** or **Add source**.+- **Hand off** asks the Content Agent to fix the open suggestions in one run, as changes for you to review; your to-dos stay yours. In **Settings › Content**, admins and managers can have each brand's new pages handed off on their own when they're first opened in the editor.++With Quality on, the header also has:++- **Next step**: the page's next step (plan the page, write the first draft, fix open rules, add proof and author, check and mark ready), with a button to take it, **Skip this step** and **All steps**.+- the page's author, picked from **Settings › Authors** (real people only: the Content Agent can't add or invent authors), and, for a page that advises on health, money or the law, the qualified person who reviewed it.+- **Before you publish**, which **Mark ready** opens first: placeholders, alt text and links; the author; visible dates; the schema (JSON-LD) to paste if your CMS doesn't add it; and a warning when Trust is under 60. **Send to CMS** opens it only when it has something to ask about (see [Send to CMS](/guides/send-to-cms)).+### 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.+- **History** keeps earlier versions for 90 days: the live page as imported, the page before agent changes, each Mark ready and publish, each Hand off, 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).+- **Export** downloads the page as **Word**, **Excel**, **CSV**, **HTML** or **Markdown**. Excel and CSV hold the page as one row, for a CMS's import. Only the HTML file carries the schema (JSON-LD). With Quality on, **Export** opens a dialog instead: the same files, and under **Platforms** a copy of the page to paste into Webflow, WordPress, Shopify or Google Docs.- **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.- **Products** (the bag in the toolbar, or **Add › Products** on an empty line), on an online shop's draft, adds products from your catalog: search by name, pick 1 to 4 that are in stock, and **Insert**. One shows as a card, more as a grid, each with its picture, name and price (in stock before low stock, then its cheapest variant there; a sale price when it's lower), linked to its page. It goes in as an HTML block; Webflow's rich text and Framer's formatted text have no grid, so there it's a list, a product a line. A product no longer in stock by the time you insert is left out, and the editor says so. When the Content Agent writes a new buying guide, best-of list, comparison or alternatives page with a shopping path, it adds the same grid of the path's products in stock (two or more), at the end of the section that links them most.- **Send to CMS** (admins and managers) sends the page to the brand's Webflow or Framer collection as a draft item, to its WordPress site or its Wix site's Blog as a draft post, or to your workflow tool through the brand's webhook, for it to create the post in your CMS. See [Send to CMS](/guides/send-to-cms).-- **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, or send it to your CMS. On a page with a shopping path, **Before you publish** also names the product cards whose price has changed in your catalog since they went in. A card keeps its price: to show today's, replace the card by deleting it and adding the product again (**Add › Products**).+- **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, or send it to your CMS. With Quality on, **Mark ready** opens **Before you publish** first (see [Quality](#quality)). On a page with a shopping path, Before you publish also names the product cards whose price has changed in your catalog since they went in. A card keeps its price: to show today's, replace the card by deleting it and adding the product again (**Add › Products**).- **Mark published** (the Library's **Status** menu, or the header's **Next step** once the page is ready, when Quality is on): once the page is live, tell Ansvisor where. It asks for the live address, starting from the page it optimizes or your site with the page's slug, and the **Live page** tab measures that address from then. If the draft came from the Action Center, its Publish task is completed once all the action's work is live. On a published page, the header's **Published** button changes the address. A page your CMS reports live, or one published in Webflow, WordPress, Framer or Wix, gets its address on its own. An archived page is restored first.- Click **Ready** in the header to move the page back to **In review**. A task that Mark ready completed is open again (**In Progress**), unless someone changed it in the Action Center since or the action is closed.@@ -197,7 +215,7 @@ When a published page links a product that no longer sells, the check also opens### Row menu- **Status**: set the draft to In progress, In review, Ready or Published. Ready works like the editor's Mark ready. **Published** asks for the page's live address, as the editor's **Mark published** does (not for archived drafts). Moving a ready or published draft back to In progress or In review opens its task again, as the editor's **Ready** does; a published one also opens the action's Publish task again and stops its Live page being measured for the action.-- **Export Word**, **Export HTML** or **Export Markdown** for that draft.+- **Export Word**, **Export Excel**, **Export CSV**, **Export HTML** or **Export Markdown** for that draft.- **Send to CMS** (admins and managers, not for archived drafts). Beside each row's status, an icon shows its last send: on its way, sent, failed or published. Tick several rows to send up to 25 at once. See [Send to CMS](/guides/send-to-cms).- **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.diff --git a/docs/guides/content-optimization.mdx b/docs/guides/content-optimization.mdxindex b0faa76ae..c49d3b317 100644--- a/docs/guides/content-optimization.mdx+++ b/docs/guides/content-optimization.mdx@@ -1,77 +1,113 @@---title: "Content Optimization"-description: "Turn visibility gaps into editorial briefs delivered to your CMS."+description: "Find content opportunities in your visibility gaps, brief them, and send them to the editor, the Action Center or your workflow."---<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+## What this page does-The **Content Optimization** page (`/dashboard/content`) lists *opportunities* — prompts where you have a visibility gap relative to competitors. Each opportunity carries:+**Opportunities** (`/dashboard/content`) lists *content opportunities*: what to write or change so AI answers name you where they don't yet. Ansvisor suggests them on its own as tracking data comes in. An opportunity is built for a group of related prompts that one piece of content can answer, or for a single prompt. Each row shows:-- A title (the angle of attack)-- An impact rating (high / medium / low) based on prompt volume × visibility gap-- Source data (related prompt, est. AI volume, visibility, competitor gap %, intent, keywords, competitors cited)-- An "opportunity score" 0–100+- the action to take, with what it was built for: a topic and its number of prompts, **Single prompt**, or the Action Center action it came from;+- when it was **Suggested** (a dot marks the rows suggested since your last visit);+- its **Type**: **Owned** (content on your own site) or **Earned** (coverage on other sites: articles, reviews, links), and, where it applies, what to do with your page: Create, Optimize, Expand, Refresh, Consolidate or Defend;+- its **Impact** (High, Medium or Low) and its **Score**, from 0 to 100;+- its **Status**: New, Reviewed, Sent to Workflow, In Progress, Done, Dismissed or Archived.++Above the list, cards count the **Total Opportunities** and the **High Impact** ones, and give the **Avg. Score**. On plans with monthly limits, **This billing period** shows how many new opportunities and content briefs are left, and when they reset.++## Filters and export++- Search the opportunities, and narrow the list by topic, prompt, type, impact, **Source** (**System**: suggested automatically; **Manual**: made with **+ New**; **Prompt**: suggested from a prompt; **Action**: sent from an Action Center task) and status.+- **Suggested** picks a period (all time, this month, the last 30 days or your own dates) and the order: highest score, newest or oldest.+- **Archived** opportunities stay hidden unless you filter to them.+- The filters stay in the page's address, so a link opens the same view.+- **Export CSV** downloads every opportunity that matches the filters and the search, not only the page you see.++## Ask for new opportunities++**+ New** (admins and managers) suggests opportunities now, instead of waiting for the next automatic run. Pick a **Focus** (let Ansvisor choose, a topic or a prompt), or describe an idea, and how many. Duplicates of existing opportunities are skipped and don't count toward the month's opportunities.++## The opportunity panel++Each row's **…** menu has the quick actions: **Send to Editor** (or **Open draft**), **Send to Plan**, **Send to Workflow** for a new opportunity, **Open in new tab**, which opens it as a page of its own, and **Dismiss** for a new one, which you can undo from the message that appears. Send to Plan and Dismiss are for admins and managers.++Click an opportunity's title to open it in a panel beside the list. The page's address keeps it, so a link opens it too.++The panel shows what the opportunity rests on:++- **Source Data**: the related prompt, **Est. AI Volume**, your **Current Visibility**, the **Competitor Gap**, the **Strongest Competitor**, the **Search Intent**, keywords, the searches AI engines ran for the prompt, and the competitors cited. An opportunity sent from an Action Center task shows that task instead: where, why, how and when it's done.+- For a group of prompts: **Your Site** (which of your pages to work on, with their AI citations and sessions over 30 days), **Recommended Assets** (the main piece of work and any supporting ones, each of which can go to the Action Center on its own), the **Opportunity Basket** (its prompts, and the searches AI engines ran for them) and **Why This Score**: demand 40%, visibility gap 30%, competitor gap 20% and intent 10%, measured over the last 30 days.+- **Results**: the Action Center actions sent from it, with what changed once their work is complete and measured.++Its buttons:++- **Send to Actions** makes it an action in the Action Center, then reads **Open in Actions**.+- **Generate Brief** writes a content brief (see below).+- **Send to Editor** opens **New content** with the opportunity picked: a new page, or the page of yours it names to optimize. Once a draft is being written for it, the button reads **Open draft**. It's offered for owned opportunities that are still open.+- **Export** downloads the opportunity as CSV, Excel or Word.+- In the **…** menu: **Send to Plan** (admins and managers), **Another angle**, **Send to Workflow** (**Send Again** once sent), **Copy All Data**, **Mark as reviewed** for a new one, **Restore** for an archived one (it comes back as New), and **Dismiss**.++**Another angle** (admins and managers) writes one more opportunity for the same need, with a different content type, format, audience or approach, and an optional direction from you. Both stay in the list, so you keep the one you prefer. It counts as one of the month's new opportunities.++**Dismiss** (admins and managers) asks why. **The topic doesn't matter to us** keeps it from being suggested again in this form for 90 days. **Right topic, wrong angle** dismisses it and opens **Another angle**.## From opportunity to brief<Steps>- <Step title="Click into an opportunity">- Navigate from the list to the detail page. You see the full source data and any existing brief.+ <Step title="Open an opportunity">+ Click its title in the list. The panel shows its source data and any brief it has.</Step><Step title="Generate Brief">- If no brief exists, click **Generate Content Brief**. An LLM produces a structured brief with:- - Suggested article title- - Content type (technical preview, comparison, how-to, listicle, etc.)- - Target word count- - Outline (5–8 sections, each with key points)- - Target keywords (5–8 SEO + AEO blended)- - Competitor insights paragraph (what rivals are doing right, where the gap is, what to attack)- - Call to action recommendation+ Admins and managers click **Generate Brief**. AI writes a brief, in your brand's language, with:+ - a suggested title+ - a content type (blog post, comparison page, landing page, FAQ page, guide or case study)+ - a target word count+ - keywords+ - a call to action+ - an outline of 3 to 8 sections, each with its key points+ - competitor insights: the competitors cited and their visibility advantage++ A brief is written once per opportunity: the button then reads **Brief Generated**. Each brief counts toward the month's content briefs.</Step>- <Step title="Send to your workflow">- Click **Send to workflow** to fire a webhook with the brief payload. The opportunity status moves from `new` → `sent`.+ <Step title="Write it, or hand it on">+ **Send to Editor** starts the page in the Content Editor, with the brief's outline and keywords as its brief. **Send to Actions** puts the work in the Action Center, and **Send to Workflow** sends it to your webhook.</Step>- <Step title="Mark as done after publishing">- Once your team ships the article, mark the opportunity as `done`. Ansvisor monitors the related prompt; if visibility climbs ≥10% in the following 4 weeks, you'll get a "win recap" notification.+ <Step title="Follow it to Done">+ Once it's in the Action Center, the opportunity's status follows its action: **In Progress** once work on it starts, **Done** when it's complete. Its **Results** card shows what changed once the work has been measured.++ A done opportunity comes back as **New**, marked **New signal detected**, when its score has risen since, or the visibility its work gained didn't hold.</Step></Steps>## Webhook configuration-Set up a webhook once, fire briefs at it from any opportunity:--- Open `/dashboard/content` and click **Webhook settings** in the toolbar-- Set the **URL** (e.g. Notion automation, Zapier, Linear webhook, custom endpoint)-- Set a **secret** (HMAC-signed payloads — recommended)-- Toggle **Active**--Payload schema:-```json-{- "opportunityId": "uuid",- "brandId": "uuid",- "brandName": "string",- "opportunity": { ...full opportunity object... },- "brief": { ...full brief object... },- "sentAt": "2026-05-06T10:00:00Z"-}-```+Set up a webhook once, and send opportunities to it from the list or the panel. Click **Webhook Settings** at the top of the page:++- **Webhook URL**: your workflow tool's address (n8n, Make, Zapier or your own endpoint).+- **Secret Key (optional)**: sent with every request in the `X-Webhook-Secret` header, so your endpoint can tell the call came from Ansvisor. Your workflow also needs it to report an opportunity's status back.+- **Events to send**: **Opportunity sent**, **Daily Pulse created**, **Action Center task sent** and **Content page sent**. A new webhook has the first three ticked; **Content page sent** stays off until you tick it. **Test Webhook** always sends a test event.+- **Active**: turn it off to pause sending without deleting the webhook.++Only admins and managers can change or test the webhook.++**Send to Workflow** sends the opportunity, the data behind it and its brief, if it has one, and moves it to **Sent to Workflow**. The webhook needs **Opportunity sent** ticked. An address that redirects isn't followed, so nothing is sent: use the address it redirects to. The payload's fields, and the callback your workflow can use to move the opportunity on (to In Progress or Done, for example), are described in [Webhooks](/api-reference/webhooks).## Bulk operations-On the listing page you can:-- Multi-select opportunities and **bulk send to webhook** (great for kicking off a content sprint)-- Bulk update status (mark a batch as `dismissed` if they're not relevant this quarter)+Tick rows, or the box in the header for every row shown, and:++- **Send All** sends each one to your webhook (great for kicking off a content sprint).+- **Done**, **Dismiss All** and **Delete** (admins and managers) change them all at once. **Delete** removes them for good, with any brief they have, and doesn't give back the month's opportunities or briefs. Dismissing keeps them out of your way instead.## Strategy notes- **Don't ship every brief** — pick the top 2–4 high-impact opportunities per week. Editorial bandwidth is the bottleneck.-- **Re-generate briefs after publishing** — once you've shipped one piece, regenerate adjacent briefs; the AI now has different competitive context-- **Mix owned and earned** — some opportunities are best closed with a guest post or PR placement (`type: earned`), not a new owned page+- **Refresh the brief in the editor** — an opportunity's brief is written once. Once the page is in the Content Editor, **Rebuild brief** writes a new one from the sources you keep there.+- **Mix owned and earned** — some opportunities are best closed with a guest post or PR placement (type **Earned**), not a new owned page. Earned opportunities don't go to the editor: send them to the Action Center or your workflow.<Card title="Self-host setup" icon="server" href="/self-host/docker-compose">Ready to run Ansvisor on your own infrastructure?diff --git a/docs/guides/topics.mdx b/docs/guides/topics.mdxindex 8a1e99935..42a7f5510 100644--- a/docs/guides/topics.mdx+++ b/docs/guides/topics.mdx@@ -5,14 +5,29 @@ description: "Cluster prompts by theme and see which areas your brand wins or lo## What is the Topics view?-The **Topics** view (Prompts → Topics, `/dashboard/prompts/topics`; the old `/dashboard/topics` address redirects there) groups your tracked prompts by theme so you can see AEO performance at a higher level than individual prompts. Each topic shows:+The **Topics** view (**Prompts → Topics**, `/dashboard/prompts/topics`; the old `/dashboard/topics` address redirects there) groups your tracked prompts by theme so you can see AEO performance at a higher level than individual prompts. The date range offers 24h, 7d, 30d, 90d or custom, and opens on 24 hours.++At the top, four cards sum up your topics:++- **Tracked topics** — how many topics you have, and how many prompts have no topic yet+- **Best performer** — the topic with the highest Visibility score+- **Biggest gap** — the topic with the lowest score+- **Top mover** — the topic whose score rose most, in points++The **Topic leaderboard** below has a row per topic:- Topic name and prompt count-- Average visibility score across the topic's prompts-- Change against the window of the same length just before (the date range offers 24h, 7d, 30d, 90d or custom, and opens on 24 hours)-- Top competitor cited within the topic+- Visibility — the 0–100 score over the topic's answers, the same score as on Brand Visibility+- SoV, Mentions and Citations+- Trend — a small line and the change in points against the window of the same length just before+- Top competitor — the competitor with the largest share of voice in the topic+- Last run- One-click drill-down into the topic detail page+Click **Prompts**, **Visibility**, **SoV**, **Mentions**, **Citations** or **Last run** to sort by it; the table opens sorted by Visibility.++The buttons beside the tabs are **Add Topic**, **Export CSV** (the leaderboard as a CSV file) and **Manage topics**.+## When to use it- **Editorial planning** — pick the topic with the lowest score and weakest competitor lead; that's your next content sprint@@ -21,23 +36,32 @@ The **Topics** view (Prompts → Topics, `/dashboard/prompts/topics`; the old `/## Topic detail page-Clicking into a topic shows:-- Every prompt in the cluster with per-platform visibility-- Aggregated citations across the topic's prompts-- Competitor mention frequency within the topic-- A "Generate brief" CTA if the topic has open content optimization opportunities+Clicking into a topic shows all of its results, not only the date range picked on the Topics tab:++- **Visibility**, **Brand mentions**, **Citations** and **Positive sentiment** for the topic+- **Visibility trend** — your daily visibility on the topic against the competitor average+- **Share of voice by platform** — you against competitors on each answer engine+- **Competitor comparison** — the top six brands on this topic, ranked by their score, with yours marked **YOU**+- **Prompt performance** — the topic's **Top performers** and the prompts under **Needs improvement**, from its last 50 runs++**View all prompt results for this topic** opens Brand Visibility filtered to the topic.++## Suggested topics++The **Topic Suggestions** card on the Topics tab starts folded. Open it to see AI-generated topic ideas for your brand; topics you already track and ideas you dismissed don't come back. Admins and managers can **Refresh** for new ideas, add an idea to your topics, or dismiss it. A new topic starts empty: assign prompts to it to start tracking it.## Editing topics-From the Topics view you can:-- **Rename** a topic (the underlying prompts stay attached)-- **Merge** two topics — useful when AI suggestions create slightly different labels for the same theme-- **Delete** a topic (prompts become un-categorized)+Only admins and managers can change topics; other roles can view them.++- **Add Topic** creates a new, empty topic.+- To **delete** a topic, open the **…** menu at the end of its row › **Delete topic**. The dialog says how many prompts are in the topic. They aren't deleted: they keep their tracking and results, and move to prompts without a topic. After you confirm, **Undo** puts the topic back for 10 seconds.+- **Manage topics** opens the brand's topic settings, where you can also **rename** a topic (the pencil icon). Its prompts stay attached.<Tip>Keep topic names short (2–4 words) and intent-driven. *"EV Range"* is better than *"Electric Vehicle Driving Distance Comparisons"*.</Tip><Card title="Continue: Prompts" icon="arrow-right" href="/guides/prompts">- Manage tracked prompts and use the Suggestions card to expand coverage.+ Manage tracked prompts and use Prompt Suggestions to expand coverage.</Card>