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: add Mintlify docs scaffold and align README features with sidebar
Gökhan Geyikcd68523f5876
diff --git a/README.md b/README.mdindex 42617bcc1..0f2ec51fb 100644--- a/README.md+++ b/README.md@@ -23,13 +23,15 @@ Track how your brand appears in answers from ChatGPT, Gemini, Perplexity, Claude## Features-- **AI Search Tracking** — Monitor how AI engines (ChatGPT, Gemini, Perplexity, Grok, Claude) mention your brand-- **Brand Visibility Analytics** — Real-time dashboard with visibility scores and trend analysis-- **Competitor Tracking** — Compare your AI presence against competitors-- **Content Optimization** — AI-powered suggestions to improve your brand's representation-- **Prompt Volume Analysis** — Understand search demand across AI platforms+- **Answer Engine Insights** — Real-time visibility scores across ChatGPT, Gemini, Perplexity, Claude, Copilot and Grok with weekly trend analysis+- **Topics** — Cluster prompts by intent and topic so you can see exactly which themes your brand wins or loses+- **Prompts** — Track unlimited natural-language queries, get AI-generated prompt suggestions based on competitor citations, and analyze monthly search volume per prompt+- **Citations** — See every URL AI engines cite alongside your brand, classified by source type (news, review, owned, social, forum)+- **AI Traffic Analytics** — Tracking pixel that measures real visits arriving from AI answer engines, with platform breakdown, top landing pages, and country segmentation+- **Competitors** — Compare your AI presence against named competitors and surface visibility gaps to close+- **Content Optimization** — AI-generated content briefs (title, outline, target keywords, competitor insights) with one-click webhook delivery to your CMS or workflow- **Multi-language Support** — 13 languages, 18 regions-- **Self-hosted or Cloud** — Run on your own infrastructure with all features unlocked+- **Self-hosted or Cloud** — Run it on your own infrastructure with every feature unlocked, or use the managed cloud at [ansvisor.com](https://ansvisor.com)## Quick Startdiff --git a/docs/api-reference/authentication.mdx b/docs/api-reference/authentication.mdxnew file mode 100644index 000000000..4c4a1400b--- /dev/null+++ b/docs/api-reference/authentication.mdx@@ -0,0 +1,58 @@+---+title: "Authentication"+description: "How to authenticate API requests to the Ansvisor server."+---++## Bearer token++All `/api/*` endpoints on the Ansvisor server require a Supabase JWT bearer token in the `Authorization` header:++```bash+curl https://api.your-domain.com/api/health \+ -H "Authorization: Bearer <SUPABASE_JWT>"+```++## Getting a token++The cleanest way is via the Supabase JS client in your own backend code:++```ts+import { createClient } from '@supabase/supabase-js';++const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);+const { data: { session } } = await supabase.auth.signInWithPassword({+ email,+ password,+});++const token = session.access_token;+```++The web app does this automatically — every server action and fetch attaches the current session token transparently.++## Cron endpoints++A handful of internal endpoints (used by Vercel Cron and Stripe success callbacks) authenticate via a shared `CRON_SECRET` instead of user tokens:++```bash+curl https://api.your-domain.com/cron/daily-tracking \+ -H "Authorization: Bearer $CRON_SECRET"+```++The same secret must be configured on both sides (Vercel env + server env).++## Public endpoints++Three endpoints don't require any auth:++- `GET /t.js` — tracking pixel script+- `POST /t/collect` — tracking pixel beacon (validates origin against `brand_domains`)+- `GET /healthz` (where exposed) — basic uptime check++<Note>+The internal `/api/health` endpoint described in the routes file IS auth-protected — by design, it returns the authenticated user's ID. For uptime monitoring, use `/t.js` instead (returns 200 + JS content).+</Note>++<Card title="Continue: Brands API" icon="arrow-right" href="/api-reference/brands">+ CRUD endpoints for managing brands programmatically.+</Card>diff --git a/docs/api-reference/brands.mdx b/docs/api-reference/brands.mdxnew file mode 100644index 000000000..1410ffdae--- /dev/null+++ b/docs/api-reference/brands.mdx@@ -0,0 +1,68 @@+---+title: "Brands"+description: "List, create, and manage brands programmatically."+---++<Note>+Most brand CRUD lives in the **web** app's server actions, not the standalone Express server. The endpoints below describe the public-facing patterns; the underlying tables live in Supabase and are accessible via the Supabase REST/RPC API directly with appropriate RLS-protected keys.+</Note>++## List brands++```http+GET /rest/v1/brands?select=*,brand_domains(*),competitors(*)+Authorization: Bearer <SUPABASE_JWT>+apikey: <SUPABASE_ANON_KEY>+```++Returns brands the authenticated user's organization can see (RLS-filtered).++## Create a brand++```http+POST /rest/v1/brands+Content-Type: application/json+Authorization: Bearer <SUPABASE_JWT>+apikey: <SUPABASE_ANON_KEY>++{+ "organization_id": "uuid",+ "name": "Acme Corp",+ "slug": "acme-corp",+ "industry": "SaaS",+ "region": "US",+ "language": "en"+}+```++After creation, you'll typically follow up with:+- `POST /rest/v1/brand_domains` — register the primary domain+- `POST /rest/v1/competitors` — add competitor records+- `POST /rest/v1/prompt_sets` + `POST /rest/v1/prompts` — set up the tracked prompt list++## Update a brand++```http+PATCH /rest/v1/brands?id=eq.<uuid>+Content-Type: application/json+Authorization: Bearer <SUPABASE_JWT>++{ "industry": "B2B SaaS" }+```++## Delete a brand++```http+DELETE /rest/v1/brands?id=eq.<uuid>+Authorization: Bearer <SUPABASE_JWT>+```++Cascade-deletes all related rows: prompts, results, citations, suggestions, traffic logs.++## Schema reference++See [Supabase setup → schema](/self-host/supabase-setup) for the full table definitions and relationships.++<Card title="Continue: Tracking API" icon="arrow-right" href="/api-reference/tracking">+ Trigger and inspect AI tracking jobs.+</Card>diff --git a/docs/api-reference/tracking.mdx b/docs/api-reference/tracking.mdxnew file mode 100644index 000000000..62a77a241--- /dev/null+++ b/docs/api-reference/tracking.mdx@@ -0,0 +1,83 @@+---+title: "Tracking"+description: "Trigger AI engine queries and inspect tracking jobs."+---++## Trigger a tracking run++```http+POST /api/tracking/start+Content-Type: application/json+Authorization: Bearer <SUPABASE_JWT>++{+ "brandId": "uuid",+ "platforms": ["chatgpt", "gemini", "perplexity"],+ "models": ["gemini-2.5-flash"]+}+```++Enqueues a tracking job. Returns:++```json+{+ "success": true,+ "jobId": "job-uuid"+}+```++## Poll job status++```http+GET /api/tracking/job/{jobId}+Authorization: Bearer <SUPABASE_JWT>+```++Returns:++```json+{+ "status": "active",+ "progress": { "phase": "querying-platforms", "completed": 12, "total": 30 },+ "result": null,+ "failedReason": null+}+```++`status` values: `waiting`, `active`, `completed`, `failed`, `cancelled`.++## Internal cron endpoint++The web app's cron route (`/api/cron/daily-tracking`) calls the server's internal endpoint with a shared secret:++```http+POST /cron/daily-tracking+Authorization: Bearer <CRON_SECRET>+```++This loops over every brand in the org, picks brands due for refresh based on `brand_platforms.check_frequency`, and enqueues tracking jobs for them.++<Note>+Vercel Cron triggers `/api/cron/daily-tracking` on a schedule defined in `web/vercel.json`. To run the same flow manually for testing, hit the server endpoint directly with the cron secret.+</Note>++## Latest results++For UI rendering, prefer the optimized RPC:++```http+POST /rest/v1/rpc/get_latest_prompt_results+Content-Type: application/json+Authorization: Bearer <SUPABASE_JWT>++{+ "p_brand_id": "uuid",+ "p_platform": "chatgpt" // optional+}+```++Returns the most recent `prompt_results` row per `(prompt_id, platform)` — much cheaper than `SELECT … ORDER BY created_at DESC LIMIT 1` per prompt in app code.++<Card title="Continue: Webhooks" icon="arrow-right" href="/api-reference/webhooks">+ Outbound webhooks for content briefs and lifecycle events.+</Card>diff --git a/docs/api-reference/webhooks.mdx b/docs/api-reference/webhooks.mdxnew file mode 100644index 000000000..09f3fe095--- /dev/null+++ b/docs/api-reference/webhooks.mdx@@ -0,0 +1,102 @@+---+title: "Webhooks"+description: "Outbound webhooks for content briefs and lifecycle events."+---++## Configuration++Webhooks are configured per-brand via the `webhook_configs` table. The dashboard UI for this lives in **Content → Webhook settings**.++Required fields:+- `webhook_url` — your endpoint+- `webhook_secret` — used to HMAC-sign payloads (recommended)+- `events` — array of subscribed events (currently: `content_brief.sent`, `opportunity.created`, `opportunity.status_changed`)+- `is_active` — toggle without deleting++## Payload format++All webhooks use the same envelope:++```json+{+ "event": "content_brief.sent",+ "occurredAt": "2026-05-06T10:00:00Z",+ "brandId": "uuid",+ "brandName": "Acme Corp",+ "data": { ... event-specific payload ... }+}+```++## Signature verification++If `webhook_secret` is set, Ansvisor signs each payload with HMAC-SHA256:++```+X-Ansvisor-Signature: sha256=<hex digest>+X-Ansvisor-Timestamp: <unix ms>+```++Verification (Node example):++```js+import crypto from 'crypto';++function verify(rawBody, signatureHeader, timestampHeader, secret) {+ const expected = crypto+ .createHmac('sha256', secret)+ .update(`${timestampHeader}.${rawBody}`)+ .digest('hex');+ const sig = signatureHeader.replace('sha256=', '');+ return crypto.timingSafeEqual(+ Buffer.from(sig, 'hex'),+ Buffer.from(expected, 'hex'),+ );+}+```++Reject any payload where:+- Signature mismatches+- Timestamp is older than 5 minutes (replay protection)++## Event reference++### `content_brief.sent`++Fired when a user clicks "Send to workflow" on a content opportunity.++```json+{+ "event": "content_brief.sent",+ "data": {+ "opportunityId": "uuid",+ "opportunity": { ...full opportunity object... },+ "brief": { ...full brief object... }+ }+}+```++### `opportunity.created`++Fired when the content optimization worker generates a new opportunity.++### `opportunity.status_changed`++Fired when an opportunity moves between statuses (`new` → `sent` → `in_progress` → `done` / `dismissed`).++## Retries++Failed deliveries (non-2xx response, timeout, connection error) retry with exponential backoff:+- Attempt 1 — immediately+- Attempt 2 — after 30 seconds+- Attempt 3 — after 5 minutes+- Attempt 4 — after 30 minutes++After 4 failed attempts, the delivery is marked failed and logged to `webhook_response`. No further retries are attempted automatically — you can resend manually from the dashboard.++## Testing++The Content → Webhook settings page includes a **Test webhook** button that fires a synthetic `content_brief.sent` event so you can validate your endpoint before going live.++<Card title="Help center" icon="circle-question" href="/faq">+ Common questions and troubleshooting.+</Card>diff --git a/docs/concepts/topics-and-prompts.mdx b/docs/concepts/topics-and-prompts.mdxnew file mode 100644index 000000000..88e6b00f9--- /dev/null+++ b/docs/concepts/topics-and-prompts.mdx@@ -0,0 +1,80 @@+---+title: "Topics and Prompts"+description: "The two primitives that drive every Ansvisor measurement."+---++## Prompt = a single tracked query++A **prompt** is one natural-language question your potential customer might ask an AI engine. Examples:++- *"best CRM for small business"*+- *"how to automate email marketing for ecommerce"*+- *"ChatGPT alternatives for enterprise"*+- *"longest range luxury EV available in the US"*++Each prompt runs on a schedule across the AI engines you've configured (ChatGPT, Gemini, Perplexity, Claude, Copilot, Grok). Every run produces a stored response with mention count, citations, sentiment, competitor mentions, and a visibility score for that prompt.++## Topic = a cluster of related prompts++A **topic** is a label you (or the AI suggestion engine) attach to one or more prompts. Topics group prompts by intent, theme, or product area:++| Topic | Example prompts |+|---|---|+| **Reliability** | *most reliable luxury sedan according to Consumer Reports*, *which luxury cars have lowest 10-year ownership cost* |+| **EV Range** | *longest range luxury EV available in the US*, *best electric SUV with 300+ mile range* |+| **Pricing** | *cheapest luxury brand to maintain long term*, *best executive sedans under $100k* |++Topics serve three purposes:++<Steps>+ <Step title="Aggregate analysis">+ The Topics page shows visibility per topic, so you spot which themes your brand owns and which it's losing.+ </Step>+ <Step title="Content planning">+ Content briefs are generated per topic, ensuring your editorial output covers your weakest themes first.+ </Step>+ <Step title="Prompt suggestions">+ When Ansvisor suggests new prompts to track, each suggestion comes with a topic label so you can see at a glance whether it expands an existing theme or opens a new one.+ </Step>+</Steps>++## How prompts get into the system++Three sources:++1. **Onboarding suggestions** — when you create a brand, Ansvisor's AI generates 10 starter prompts based on industry and description.+2. **Prompt Suggestions** in the Insights tab — periodically, Ansvisor analyzes your tracked prompts + competitor citations + topic gaps and suggests new prompts to add. Each comes with a one-click `+` button.+3. **Manual entry** — you can always add a prompt directly with custom text and platform/region selection.++## How topics get created++Two paths:++- **Auto-created from suggestions** — when a new prompt suggestion comes with a topic label that doesn't exist for your brand yet, accepting the prompt creates the topic too.+- **Manual** — you can rename, merge, or create topics on the Topics page. A prompt can belong to one topic at a time.++## Practical workflow++A typical AEO operator's loop on Ansvisor:++<Steps>+ <Step title="Review Insights weekly">+ Check overall visibility delta. Drill into topics that dropped most.+ </Step>+ <Step title="Inspect prompts in losing topics">+ Find which prompts dragged the topic down — usually 1–2 prompts where a competitor surged.+ </Step>+ <Step title="Generate content briefs">+ Click "Generate Brief" on those opportunities; receive structured brief (title, outline, keywords, competitor angles).+ </Step>+ <Step title="Send to your CMS or workflow">+ Use the webhook integration to push the brief directly into Notion, Linear, Asana, or your editorial system.+ </Step>+ <Step title="Add new prompts from Suggestions">+ Pick up 1–3 fresh prompts each week from the Suggestions card to expand your tracked surface.+ </Step>+</Steps>++<Card title="Continue: Add your first brand" icon="arrow-right" href="/guides/add-your-first-brand">+ Walk through the brand onboarding step by step.+</Card>diff --git a/docs/concepts/visibility-scoring.mdx b/docs/concepts/visibility-scoring.mdxnew file mode 100644index 000000000..6922ccfe5--- /dev/null+++ b/docs/concepts/visibility-scoring.mdx@@ -0,0 +1,69 @@+---+title: "Visibility scoring"+description: "How Ansvisor computes a 0–100 visibility score per brand, prompt, and platform."+---++## 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.++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.++## 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:++<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>+ <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>+ <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>+</Steps>++The result is a 0–100 number per `(prompt, platform, run)` triple.++## Aggregation++Dashboard visibility scores aggregate across multiple dimensions:++- **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++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.++## What moves your score++| Action | Effect |+|---|---|+| Publish a citation-friendly comparison page | + over 1–4 weeks as LLMs re-index |+| Earn coverage on a major review/listicle site | + within 2–7 days, often immediately |+| Lose a press citation (article retracted) | – within a week |+| A competitor outpaces you with better structured data | – relative score declines |+| Add new prompts to your tracked set | Score may dip until those prompts mature |++## What does NOT move your score++- Pure PageRank / backlinks without on-page content+- Frequency of social posts (LLMs heavily underweight social vs. published content)+- Time spent on traditional SEO without addressing AEO content patterns++<Tip>+**Healthy growth target**: a 5–10% relative improvement per month is realistic for a focused AEO program in a competitive category. Anything faster usually requires either a major press placement or a structural content investment (e.g. publishing 30+ comparison pages in a quarter).+</Tip>++## 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++<Card title="Continue: Topics and Prompts" icon="arrow-right" href="/concepts/topics-and-prompts">+ How prompts cluster into topics and why that matters.+</Card>diff --git a/docs/concepts/what-is-aeo.mdx b/docs/concepts/what-is-aeo.mdxnew file mode 100644index 000000000..22eaf5b56--- /dev/null+++ b/docs/concepts/what-is-aeo.mdx@@ -0,0 +1,57 @@+---+title: "What is AEO?"+description: "Answer Engine Optimization — the discipline of being cited by AI search engines."+---++## SEO is for the 10 blue links. AEO is for the answer.++For 25 years, organic discovery has meant ranking high on a Google results page. The strategy is well-known: keywords, backlinks, page speed, schema markup. The user clicks a result, lands on your site, you measure the visit.++That funnel is shrinking. Tools like ChatGPT, Gemini, Perplexity, Claude, and Copilot give users a **direct answer** with a small handful of citations — and increasingly the user never clicks at all. ChatGPT alone serves over 200 million queries a day. Each one of those queries is a chance for an AI assistant to recommend your brand or recommend a competitor.++**Answer Engine Optimization (AEO)** is the practice of making sure your brand is the one the AI cites.++## How AEO differs from SEO++| | SEO | AEO |+|---|---|---|+| **Target surface** | Google SERP | AI assistant answers |+| **Unit of optimization** | Page rank | Brand mention frequency |+| **Signal source** | Crawled HTML, backlinks | LLM training data + retrieval |+| **Measurement** | Position, impressions, CTR | Mention rate, citation share, answer presence |+| **Time to impact** | Weeks to months | Daily/weekly (LLMs re-index quickly) |+| **Killer asset** | Long-form content + links | Structured, citation-friendly content + topical authority |++SEO and AEO are complementary, not competitive — both feed off authoritative content. But the *measurement system* is fundamentally different. You can't open Google Search Console and ask "how often did ChatGPT cite us last week?" That's the gap Ansvisor fills.++## What AEO looks like in practice++Three things move the needle in AI engine answers:++<Steps>+ <Step title="Topical authority signals">+ AI engines surface brands that have **broad, deep content** on a topic. A single great post is rarely enough; consistent coverage of the topical cluster is.+ </Step>+ <Step title="Citation-friendly content structure">+ Bullet lists, comparison tables, structured FAQs, schema markup, named-entity-rich text. Content that's easy for an LLM to extract verbatim is content that gets cited.+ </Step>+ <Step title="Third-party validation">+ Press, reviews, listicles, Reddit/Quora threads. AI engines weight third-party sources heavily because they reduce hallucination risk. Earned media is now an SEO+AEO double-win.+ </Step>+</Steps>++## What Ansvisor measures++Every Ansvisor brand starts with a list of **prompts** — natural-language questions your potential customers ask AI engines (e.g. *"best CRM for small business"*, *"alternatives to Salesforce"*). Multiple times per week, Ansvisor:++1. Asks each prompt to every configured AI engine+2. Parses the response for brand mentions, citation URLs, and competitor mentions+3. Computes a **visibility score** per brand, per prompt, per platform+4. Surfaces gaps: prompts where competitors are cited but you aren't+5. Generates content briefs targeting those gaps++The output is a continuously-updated AEO instrumentation panel. Same way Google Analytics changed how marketers measure SEO, Ansvisor is built to be the AEO equivalent.++<Card title="Continue: How visibility is scored" icon="arrow-right" href="/concepts/visibility-scoring">+ Learn the math behind your visibility score and what changes it.+</Card>diff --git a/docs/faq.mdx b/docs/faq.mdxnew file mode 100644index 000000000..dd28a9b9b--- /dev/null+++ b/docs/faq.mdx@@ -0,0 +1,50 @@+---+title: "FAQ"+description: "Common questions about Ansvisor."+---++<AccordionGroup>+ <Accordion title="Is Ansvisor really fully open source?">+ Yes. Every line of code that powers ansvisor.com is in the [public repo](https://github.com/aeohub/ansvisor) under MIT. No paywalled features in the self-hosted build — the cloud service is just a hosted convenience.+ </Accordion>++ <Accordion title="What's the cost difference between cloud and self-hosted?">+ Cloud has a flat monthly subscription that includes everything (AI provider quotas, infrastructure, support). Self-hosted is free in software cost but you pay your own AI provider bills (OpenAI, Gemini, Anthropic) plus DataForSEO/Cloro if you use them.++ Rough back-of-envelope: a brand tracking 30 prompts daily across 4 AI engines costs ~$5–15/month in API fees, depending on response length and provider mix.+ </Accordion>++ <Accordion title="Why don't you scrape ChatGPT/Gemini directly?">+ For programmable AI engines (OpenAI, Anthropic, Google Gemini API), Ansvisor uses official APIs — most reliable, well-priced, and TOS-compliant. For *web* AI engines that don't have public APIs (like ChatGPT.com search results), Ansvisor uses Cloro as a managed scraping backend. Cloro handles browser fingerprinting, captcha bypass, and rate-limiting at scale.+ </Accordion>++ <Accordion title="How often does tracking run?">+ Default schedule is once per day per brand. You can configure per-platform frequency under brand settings (e.g. ChatGPT daily, Perplexity 3x/week, Gemini weekly) to manage AI provider costs.+ </Accordion>++ <Accordion title="My visibility score is 0. Did setup go wrong?">+ Probably not. Brand-new brands or those in non-English-language niches commonly start at 0 across most prompts. The score reflects what AI engines *currently* cite — closing that gap with content + earned media is exactly what AEO is for.+ </Accordion>++ <Accordion title="Can I see the actual AI responses, not just metrics?">+ Yes. Click any prompt or platform cell on the Insights page; the drill-down sheet shows the full LLM response, parsed citations, sentiment, and detected competitor mentions.+ </Accordion>++ <Accordion title="How do I get help?">+ - **Bugs / feature requests**: [GitHub Issues](https://github.com/aeohub/ansvisor/issues)+ - **Discussion**: [GitHub Discussions](https://github.com/aeohub/ansvisor/discussions)+ - **Cloud customers**: support email in your dashboard footer+ </Accordion>++ <Accordion title="Is my data private?">+ For self-hosted: 100% on your infrastructure, never touches Ansvisor servers. For cloud: standard SaaS privacy — your prompts and responses are stored in our managed Supabase, isolated per organization via RLS, never used for training. Full DPA available on request for enterprise plans.+ </Accordion>++ <Accordion title="Does Ansvisor work for non-English brands?">+ Yes — 13 languages and 18 regions supported. AI engines respond in the language of the prompt; Ansvisor's mention/citation parsing is language-agnostic.+ </Accordion>++ <Accordion title="How do I contribute?">+ Read [CONTRIBUTING.md](https://github.com/aeohub/ansvisor/blob/main/CONTRIBUTING.md) in the repo. We welcome PRs for: new AI engine adapters, additional citation classifiers, language packs, UI polish, and bug fixes. For larger features, open an issue first to align.+ </Accordion>+</AccordionGroup>diff --git a/docs/guides/add-your-first-brand.mdx b/docs/guides/add-your-first-brand.mdxnew file mode 100644index 000000000..c28360526--- /dev/null+++ b/docs/guides/add-your-first-brand.mdx@@ -0,0 +1,74 @@+---+title: "Add your first brand"+description: "Step-by-step walkthrough of brand onboarding."+---++## Prerequisites++- A logged-in Ansvisor account ([cloud](https://ansvisor.com/sign-up) or [self-hosted](/self-host/docker-compose))+- 5–10 minutes+- The primary domain you want to track++## Walkthrough++<Steps>+ <Step title="Open the Add Brand flow">+ From the dashboard, click **Brands** in the sidebar, then **+ Add Brand** (or visit `/dashboard/brands/new` directly).+ </Step>+ <Step title="Enter brand basics">+ - **Brand name** — exactly how the brand is named in the wild (e.g. *Mercedes-Benz*, not *MBZ*). Casing matters because mention detection matches case-insensitively but suggestions copy your spelling.+ - **Primary domain** — your main website (`mbusa.com`, `linear.app`). Used for citation classification and AI traffic attribution.+ - **Industry** — a free-text or selected category. Drives default prompt suggestions.+ - **Region** — primary market (US, EU, TR, etc.). Affects prompt language and AI engine region routing.+ - **Description** — 1–3 sentences about what the brand does. Fed into prompt generation.+ </Step>+ <Step title="Review auto-generated prompts">+ Ansvisor generates 10 starter prompts based on your industry and description. They're shown as a checklist — review them, edit text inline, and uncheck any that don't fit. You can always add more later.++ <Tip>+ A good starter set covers: 2–3 *industry best-of* prompts, 2–3 *how-to* prompts, 2–3 *comparison/alternative* prompts, 1–2 *recommendation* prompts. Avoid brand-name-containing prompts — they don't measure organic AI mention rate.+ </Tip>+ </Step>+ <Step title="Pick AI engines">+ Select which engines run each prompt. Default is **ChatGPT + Gemini + Perplexity + Claude**. Add Copilot, Grok, or Meta AI if relevant to your audience.++ <Note>+ More engines = more API/scraper calls = higher monthly cost in cloud mode. Self-hosted is unlimited.+ </Note>+ </Step>+ <Step title="Add competitors (optional but recommended)">+ Enter 2–5 competitor names. The competitor tracking module needs at least one to work. Names should be exactly as you'd see them in an AI response (e.g. *Salesforce*, *HubSpot*).+ </Step>+ <Step title="Configure tracking pixel (optional)">+ If you want **AI Traffic Analytics** (visits arriving from AI answer engines), grab the snippet from the Traffic page and paste it before `</head>` on your site. Tracking starts immediately.+ </Step>+ <Step title="Save and trigger first run">+ Click **Save brand**. The first round of AI engine queries kicks off automatically — usually completes in 5–15 minutes. You'll get an email when results are ready, but the dashboard updates live as data comes in.+ </Step>+</Steps>++## What to do while you wait++The first tracking run takes a few minutes. Useful things to do during that time:++- **Insights tab** will populate first — even before all platforms finish, you can already see the first prompts coming in+- Browse the **Citations** page to see which third-party URLs are showing up+- Skim the **Suggestions** card on the Insights tab — it'll have AI-generated prompt ideas based on your initial run++## Common pitfalls++<AccordionGroup>+ <Accordion title="My visibility score is 0 — is something broken?">+ Probably not. New, niche, or B2B brands often start at 0 across most prompts. AI engines need (1) significant training data mentioning your brand, or (2) live citations from authoritative sources. The score only stays at 0 when both are missing — fixing that 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 obviously talks about you when asked) but they're not measuring organic discovery. Remove brand-name prompts from your tracked set; they distort averages.+ </Accordion>+ <Accordion title="I see weird competitors I never heard of in my results">+ That's gold. Those are AI-suggested alternatives users see when you're not cited. Add the most-mentioned ones to your competitors list to track them properly.+ </Accordion>+</AccordionGroup>++<Card title="Continue: Reading Answer Engine Insights" icon="arrow-right" href="/guides/answer-engine-insights">+ Now that data is flowing, learn to read the dashboard.+</Card>diff --git a/docs/guides/ai-traffic-analytics.mdx b/docs/guides/ai-traffic-analytics.mdxnew file mode 100644index 000000000..7fa05eb9e--- /dev/null+++ b/docs/guides/ai-traffic-analytics.mdx@@ -0,0 +1,72 @@+---+title: "AI Traffic Analytics"+description: "Measure real visits to your site from AI answer engines."+---++## 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.++## Setup++<Steps>+ <Step title="Get the snippet">+ On the **AI Traffic Analytics** page (`/dashboard/traffic`), copy the snippet at the top. It looks like:+ ```html+ <script src="https://api.ansvisor.com/t.js" data-t="YOUR_TRACKING_CODE" defer></script>+ ```+ </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.+ </Step>+ <Step title="Wait for first visits">+ Visits start appearing immediately. The dashboard updates in near-realtime (≤1 minute).+ </Step>+</Steps>++## What you see++<CardGroup cols={2}>+ <Card title="KPI strip" icon="gauge-high">+ Total AI-referred visits, top platform, unique platforms — all with 7-day delta.+ </Card>+ <Card title="Trend chart" icon="chart-line">+ Daily breakdown by AI platform, last 7 days.+ </Card>+ <Card title="Platform table" icon="table-list">+ Per-platform visit counts with week-over-week change.+ </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>+</CardGroup>++## Supported AI sources++Pixel detects and classifies referrers from:++- ChatGPT (chatgpt.com, chat.openai.com, search.chatgpt.com)+- Perplexity (perplexity.ai)+- Claude (claude.ai)+- Gemini (gemini.google.com)+- Copilot (copilot.microsoft.com)+- You.com, Phind, Meta AI, Poe++Anything else falls into `unknown` — likely a future AI source we haven't catalogued yet. The list is updated regularly.++## 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.++## 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++<Card title="Continue: Competitors" icon="arrow-right" href="/guides/competitors">+ Benchmark your AI presence against named rivals.+</Card>diff --git a/docs/guides/answer-engine-insights.mdx b/docs/guides/answer-engine-insights.mdxnew file mode 100644index 000000000..cdb6a03a1--- /dev/null+++ b/docs/guides/answer-engine-insights.mdx@@ -0,0 +1,90 @@+---+title: "Answer Engine Insights"+description: "The Insights page is your daily AEO command center."+---++## What you see++The **Insights** page (`/dashboard/insights`) is the main analytics hub for a brand. It breaks down your AI visibility across four panels:++<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>+ <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>+ <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>+ <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>+</Steps>++## Reading the visibility number++A few quick interpretations to anchor you:++- **<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.+- **>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.++<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%.+</Tip>++## Common workflows++### 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>+ <Step title="Identify the trailing platform">+ Pick the platform contributing least; 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>+ <Step title="Send 1 brief to writers">+ From Content Optimization, generate a brief for the worst-performing prompt this week.+ </Step>+</Steps>++### Investigation flow (30 min)++When 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>+ <Step title="Inspect competitor mentions">+ The drill-down lists every competitor cited in that response. New competitor surge is often the cause.+ </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>+ <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.+ </Step>+</Steps>++## 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++Filters apply to all four panels simultaneously.++<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.+</Card>diff --git a/docs/guides/citations.mdx b/docs/guides/citations.mdxnew file mode 100644index 000000000..2ac6b66bc--- /dev/null+++ b/docs/guides/citations.mdx@@ -0,0 +1,50 @@+---+title: "Citations"+description: "Every URL AI engines cite alongside your brand, classified 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 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++## Source classification++Ansvisor automatically classifies citations into seven categories:++| 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 |++## 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.++### 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.++### 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.++## Drill-down++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++<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.+</Card>diff --git a/docs/guides/competitors.mdx b/docs/guides/competitors.mdxnew file mode 100644index 000000000..a8f3e24f4--- /dev/null+++ b/docs/guides/competitors.mdx@@ -0,0 +1,56 @@+---+title: "Competitors"+description: "Track named competitors and benchmark visibility side-by-side."+---++## Adding competitors++On the **Competitors** page (`/dashboard/competitors`) click `+ Add competitor`. Each competitor has:++- **Name** — exactly as it appears in AI responses (e.g. *Salesforce*, not *salesforce.com*)+- **Domain** (optional) — used for citation cross-checks++Aim for 3–8 competitors. Fewer than 3 and benchmarks have no signal; more than 8 and the comparison view gets noisy.++## 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?++## Comparison views++<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>+ <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>+ <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>+</Steps>++## 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>++## Closing visibility gaps++Once 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++<Card title="Continue: Content Optimization" icon="arrow-right" href="/guides/content-optimization">+ Generate AI content briefs to systematically close visibility gaps.+</Card>diff --git a/docs/guides/content-optimization.mdx b/docs/guides/content-optimization.mdxnew file mode 100644index 000000000..09bb9fcab--- /dev/null+++ b/docs/guides/content-optimization.mdx@@ -0,0 +1,74 @@+---+title: "Content Optimization"+description: "Turn visibility gaps into editorial briefs delivered to your CMS."+---++## 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:++- 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++## 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>+ <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+ </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>+ <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>+</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"+}+```++## 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)++## 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++<Card title="Self-host setup" icon="server" href="/self-host/docker-compose">+ Ready to run Ansvisor on your own infrastructure?+</Card>diff --git a/docs/guides/prompts.mdx b/docs/guides/prompts.mdxnew file mode 100644index 000000000..3846fd948--- /dev/null+++ b/docs/guides/prompts.mdx@@ -0,0 +1,54 @@+---+title: "Prompts"+description: "Manage tracked prompts and discover new ones with AI-powered suggestions."+---++## Two tabs++The **Prompts** page (`/dashboard/prompts`) has two tabs:++- **All Prompts** — flat list of every active prompt with visibility, mention rate, and platform breakdown+- **Insights** — volume analytics + AI-powered prompt suggestions++## 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++## Prompt Suggestions logic++The suggestion engine considers four 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).++<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.+</Tip>++## Volume Analysis (Insights tab)++For prompts where you've enabled volume analysis, you'll see:+- **Estimated monthly AI volume** (rough, derived from Google search volume + AI adoption multiplier)+- **Intent classification** (informational, commercial, navigational, transactional)+- **Keyword cluster** — the related queries that group with this prompt++Click any prompt to see per-platform results with the full AI response, parsed citations, and competitor mention list.++## 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+- Re-evaluate quarterly: archive prompts that consistently score 0 and bring nothing actionable++<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/topics.mdx b/docs/guides/topics.mdxnew file mode 100644index 000000000..a8b0e73c6--- /dev/null+++ b/docs/guides/topics.mdx@@ -0,0 +1,43 @@+---+title: "Topics"+description: "Cluster prompts by theme and see which areas your brand wins or loses."+---++## What is the Topics page?++The **Topics** page (`/dashboard/topics`) groups your tracked prompts by theme so you can see AEO performance at a higher level than individual prompts. Each topic shows:++- Topic name and prompt count+- Average visibility score across the topic's prompts+- 7-day delta+- Top competitor cited within the topic+- One-click drill-down into the topic detail page++## When to use it++- **Editorial planning** — pick the topic with the lowest score and weakest competitor lead; that's your next content sprint+- **Reporting to stakeholders** — topic-level stories ("we own EV Range, we're losing on Reliability") are easier to communicate than prompt-level metrics+- **Spotting drift** — a topic that drops while others stay flat usually signals a single competitor surge or content rot++## 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++## Editing topics++From the Topics page 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)++<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.+</Card>diff --git a/docs/introduction.mdx b/docs/introduction.mdxnew file mode 100644index 000000000..444e8d051--- /dev/null+++ b/docs/introduction.mdx@@ -0,0 +1,63 @@+---+title: "Introduction"+description: "Track how AI search engines mention your brand and turn AI visibility into a measurable channel."+---++<img+ className="block dark:hidden"+ src="/images/hero-light.png"+ alt="Ansvisor dashboard"+/>+<img+ className="hidden dark:block"+ src="/images/hero-dark.png"+ alt="Ansvisor dashboard"+/>++## What is Ansvisor?++Ansvisor is an open-source **Answer Engine Optimization** (AEO) platform. It tells you exactly how often ChatGPT, Gemini, Perplexity, Claude, Copilot and Grok name your brand when users ask buying-intent questions — and what to publish to get cited more often than your competitors.++Classical SEO measures rankings on a results page. AEO measures something different: whether an AI assistant chooses your brand to answer a question. That's the new frontier of organic discovery, and Ansvisor is the instrumentation layer for it.++<CardGroup cols={2}>+ <Card title="Quickstart" icon="rocket" href="/quickstart">+ Get from zero to your first tracked brand in under 10 minutes.+ </Card>+ <Card title="What is AEO?" icon="lightbulb" href="/concepts/what-is-aeo">+ The shift from SEO to AEO, and why it matters for your brand.+ </Card>+ <Card title="Self-host" icon="server" href="/self-host/docker-compose">+ Run Ansvisor on your own infrastructure with Docker Compose.+ </Card>+ <Card title="Try the Cloud" icon="cloud" href="https://ansvisor.com">+ Skip the setup with our managed cloud at ansvisor.com.+ </Card>+</CardGroup>++## What you get++<CardGroup cols={2}>+ <Card title="Answer Engine Insights" icon="chart-line" href="/guides/answer-engine-insights">+ Real-time visibility scores across every major AI engine, with weekly trend analysis.+ </Card>+ <Card title="Topics & Prompts" icon="tag" href="/guides/topics">+ Cluster the queries that drive AI traffic, get prompt suggestions based on competitor citations.+ </Card>+ <Card title="Citations" icon="quote-left" href="/guides/citations">+ Every URL AI engines cite alongside your brand, classified by source type.+ </Card>+ <Card title="AI Traffic Analytics" icon="chart-bar" href="/guides/ai-traffic-analytics">+ Real visit data from AI answer engines — platforms, pages, countries.+ </Card>+ <Card title="Competitors" icon="users" href="/guides/competitors">+ Side-by-side AI visibility against named competitors and gap analysis.+ </Card>+ <Card title="Content Optimization" icon="wand-magic-sparkles" href="/guides/content-optimization">+ AI-generated content briefs delivered to your CMS via webhook.+ </Card>+</CardGroup>++## Open-source and self-hostable++Ansvisor is MIT-licensed. Every feature available on the cloud is unlocked when you self-host — no feature gating, no telemetry. The repo lives at [github.com/aeohub/ansvisor](https://github.com/aeohub/ansvisor).diff --git a/docs/mint.json b/docs/mint.jsonnew file mode 100644index 000000000..1ed69b55c--- /dev/null+++ b/docs/mint.json@@ -0,0 +1,107 @@+{+ "$schema": "https://mintlify.com/schema.json",+ "name": "Ansvisor",+ "logo": {+ "light": "/logo/light.svg",+ "dark": "/logo/dark.svg"+ },+ "favicon": "/favicon.svg",+ "colors": {+ "primary": "#6366f1",+ "light": "#a5b4fc",+ "dark": "#4338ca",+ "anchors": {+ "from": "#6366f1",+ "to": "#8b5cf6"+ }+ },+ "topbarLinks": [+ {+ "name": "GitHub",+ "url": "https://github.com/aeohub/ansvisor"+ }+ ],+ "topbarCtaButton": {+ "name": "Try the Cloud",+ "url": "https://ansvisor.com"+ },+ "anchors": [+ {+ "name": "GitHub",+ "icon": "github",+ "url": "https://github.com/aeohub/ansvisor"+ },+ {+ "name": "Changelog",+ "icon": "list",+ "url": "https://github.com/aeohub/ansvisor/releases"+ }+ ],+ "tabs": [+ {+ "name": "Guides",+ "url": "guides"+ },+ {+ "name": "Self-host",+ "url": "self-host"+ },+ {+ "name": "API Reference",+ "url": "api-reference"+ }+ ],+ "navigation": [+ {+ "group": "Get Started",+ "pages": ["introduction", "quickstart"]+ },+ {+ "group": "Concepts",+ "pages": [+ "concepts/what-is-aeo",+ "concepts/visibility-scoring",+ "concepts/topics-and-prompts"+ ]+ },+ {+ "group": "Platform Guides",+ "pages": [+ "guides/add-your-first-brand",+ "guides/answer-engine-insights",+ "guides/topics",+ "guides/prompts",+ "guides/citations",+ "guides/ai-traffic-analytics",+ "guides/competitors",+ "guides/content-optimization"+ ]+ },+ {+ "group": "Self-host",+ "pages": [+ "self-host/docker-compose",+ "self-host/supabase-setup",+ "self-host/env-variables",+ "self-host/upgrading"+ ]+ },+ {+ "group": "API Reference",+ "pages": [+ "api-reference/authentication",+ "api-reference/brands",+ "api-reference/tracking",+ "api-reference/webhooks"+ ]+ },+ {+ "group": "Help",+ "pages": ["faq"]+ }+ ],+ "footerSocials": {+ "github": "https://github.com/aeohub/ansvisor",+ "website": "https://ansvisor.com"+ }+}diff --git a/docs/quickstart.mdx b/docs/quickstart.mdxnew file mode 100644index 000000000..18b2095f1--- /dev/null+++ b/docs/quickstart.mdx@@ -0,0 +1,86 @@+---+title: "Quickstart"+description: "Track your first brand in under 10 minutes — cloud or self-hosted."+---++## Pick a path++<Tabs>+ <Tab title="Managed Cloud (recommended)">++The fastest way to start. No infrastructure, no env files.++<Steps>+ <Step title="Sign up at ansvisor.com">+ Create an account at [ansvisor.com/sign-up](https://ansvisor.com/sign-up). All paid plans include a 7-day free trial.+ </Step>+ <Step title="Add your first brand">+ On the onboarding screen, enter your brand name, primary domain, and industry. Ansvisor auto-suggests starter prompts based on your industry — you can edit them or accept all.+ </Step>+ <Step title="Wait for the first tracking run">+ The first round of AI engine queries runs automatically and completes in 5–15 minutes. You'll receive an email when results are ready.+ </Step>+ <Step title="Open Answer Engine Insights">+ Once tracking finishes, head to **Insights** in the sidebar. You'll see your initial visibility score, platform breakdown, and the prompts where you're cited (or not).+ </Step>+</Steps>++ </Tab>+ <Tab title="Self-host with Docker">++For teams who want full control and zero per-seat pricing.++<Steps>+ <Step title="Clone the repo and prepare env files">+ ```bash+ git clone https://github.com/aeohub/ansvisor.git+ cd ansvisor+ cp web/.env.example web/.env+ cp server/.env.example server/.env+ ```+ Fill in Supabase URL/keys, at least one AI provider key, and Cloro API key.+ See [Self-host → Env variables](/self-host/env-variables) for the full reference.+ </Step>+ <Step title="Run database migrations">+ ```bash+ cd supabase+ supabase db push+ ```+ Or apply `supabase/migrations/*.sql` manually via the Supabase dashboard.+ </Step>+ <Step title="Start the stack">+ ```bash+ docker compose up -d+ ```+ Web is now on `http://localhost:3000`, API server on `http://localhost`.+ </Step>+ <Step title="Sign up and onboard">+ Open `http://localhost:3000`, create the first user account (becomes org admin), then follow the onboarding flow to add your first brand.+ </Step>+</Steps>++ </Tab>+</Tabs>++## What happens next++After your first tracking run completes, the dashboard fills with data. The most useful first walkthrough:++<CardGroup cols={2}>+ <Card title="Read your visibility score" icon="gauge-high" href="/guides/answer-engine-insights">+ Understand what the score means and how it's calculated.+ </Card>+ <Card title="Review citations" icon="quote-left" href="/guides/citations">+ See which third-party URLs AI engines trust to talk about you.+ </Card>+ <Card title="Find content gaps" icon="magnifying-glass-chart" href="/guides/content-optimization">+ Generate AI content briefs to close visibility gaps.+ </Card>+ <Card title="Add competitors" icon="users" href="/guides/competitors">+ Benchmark your AI presence against named rivals.+ </Card>+</CardGroup>++<Tip>+**Got stuck?** Open an issue at [github.com/aeohub/ansvisor/issues](https://github.com/aeohub/ansvisor/issues) — we read every report.+</Tip>diff --git a/docs/self-host/docker-compose.mdx b/docs/self-host/docker-compose.mdxnew file mode 100644index 000000000..f9f738a74--- /dev/null+++ b/docs/self-host/docker-compose.mdx@@ -0,0 +1,95 @@+---+title: "Docker Compose setup"+description: "Run the full Ansvisor stack on your own server in 10 minutes."+---++## Stack overview++The repo ships with two services in `docker-compose.yml`:++- **web** — Next.js 16 dashboard, port `3000`+- **server** — Express API + workers, port `80`++Plus an external dependency:+- **Supabase project** — database, auth, storage. You provide URL + keys.++## Prerequisites++- Linux host with Docker 24+ and Docker Compose v2+- Open ports `80` (API) and `3000` (web) — or front them with a reverse proxy+- A Supabase project ([free tier](https://supabase.com/) works fine)+- API keys for at least one AI provider (OpenAI, Anthropic, Google Gemini)++## Steps++<Steps>+ <Step title="Clone the repo">+ ```bash+ git clone https://github.com/aeohub/ansvisor.git+ cd ansvisor+ ```+ </Step>+ <Step title="Apply database migrations">+ Either use the Supabase CLI:+ ```bash+ cd supabase+ supabase link --project-ref YOUR_PROJECT_REF+ supabase db push+ ```+ Or paste each `.sql` file in `supabase/migrations/` into the Supabase SQL editor in order.+ </Step>+ <Step title="Configure env files">+ ```bash+ cp web/.env.example web/.env+ cp server/.env.example server/.env+ ```+ Fill in Supabase URL/keys, AI provider keys, and (optional) DataForSEO + Cloro credentials.+ See [Env variables](/self-host/env-variables) for the full reference.+ </Step>+ <Step title="Start the stack">+ ```bash+ docker compose up -d+ docker compose logs -f+ ```+ Web is now on `http://localhost:3000`, API on `http://localhost`.+ </Step>+ <Step title="Create your first user">+ Open `http://localhost:3000/sign-up` and register. The first user becomes org admin automatically.+ </Step>+</Steps>++## Production hardening++For a real deployment behind a domain (e.g. `app.example.com` + `api.example.com`):++- Front both services with **Cloudflare** (proxied) or **Caddy/Nginx** for HTTPS+- Use **AWS Security Groups** / firewall rules to restrict origin ports to known IPs+- Set `NEXT_PUBLIC_API_URL=https://api.example.com` and `ALLOWED_ORIGINS=https://app.example.com` accordingly+- Mount logs to a persistent volume or ship to a logging service++<Tip>+For solo deploys we recommend **Cloudflare proxied + Flexible SSL** for the API hostname. Zero certificate management, HTTPS works in 2 minutes.+</Tip>++## Updating to a new release++```bash+cd ansvisor+git pull+docker compose up -d --build+```++Migrations under `supabase/migrations/` run forward-only — re-running `supabase db push` is idempotent.++## Splitting web and server across hosts++Common setup: web on Vercel, server + workers on a VM.++1. Don't run `docker compose up` for web — deploy `web/` to Vercel directly via Git integration+2. On the VM, run only the server: `docker compose up -d server`+3. In Vercel, set `NEXT_PUBLIC_API_URL=https://api.your-domain.com`+4. In server's env, set `ALLOWED_ORIGINS=https://your-vercel-domain.com`++<Card title="Continue: Supabase setup" icon="arrow-right" href="/self-host/supabase-setup">+ Detailed Supabase project preparation (schema, RLS, triggers).+</Card>diff --git a/docs/self-host/env-variables.mdx b/docs/self-host/env-variables.mdxnew file mode 100644index 000000000..4fb33ebc7--- /dev/null+++ b/docs/self-host/env-variables.mdx@@ -0,0 +1,64 @@+---+title: "Environment variables"+description: "Full reference for every env var across web and server."+---++## Web (`web/.env`)++Fed to the Next.js app. Variables prefixed with `NEXT_PUBLIC_` are exposed to the browser.++| Variable | Required | Description |+|---|---|---|+| `NEXT_PUBLIC_SUPABASE_URL` | ✅ | Your Supabase project URL |+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | ✅ | Supabase anon key (public, RLS-protected) |+| `SUPABASE_SERVICE_ROLE_KEY` | ✅ | Service role key (bypasses RLS — used for server actions; never expose) |+| `NEXT_PUBLIC_API_URL` | ✅ | Server URL (e.g. `https://api.your-domain.com` or `http://localhost`) |+| `NEXT_PUBLIC_APP_URL` | ✅ | Web app URL (used for OAuth callback URLs) |+| `OPENAI_API_KEY` | optional* | OpenAI API key |+| `GOOGLE_GEMINI_API_KEY` | optional* | Google AI Studio Gemini key |+| `ANTHROPIC_API_KEY` | optional* | Anthropic Claude key |+| `PERPLEXITY_API_KEY` | optional* | Perplexity API key |+| `GROK_API_KEY` | optional* | xAI Grok key |+| `NEXT_PUBLIC_IS_CLOUD` | optional | `"true"` for the official cloud build (enables billing UI). Leave unset for self-hosted (all features unlocked). |+| `STRIPE_SECRET_KEY` | cloud only | Stripe live/test secret key |+| `STRIPE_WEBHOOK_SECRET` | cloud only | Stripe webhook signing secret |+| `CRON_SECRET` | cloud only | Shared secret for Vercel cron → server auth |++\* You need **at least one AI provider key** for tracking to work. Configure providers per-brand in the dashboard.++## Server (`server/.env`)++Fed to the Express API + workers.++| Variable | Required | Description |+|---|---|---|+| `NODE_ENV` | ✅ | `production` for live, `development` for local |+| `PORT` | ✅ | Default `80` |+| `SUPABASE_URL` | ✅ | Same as web's `NEXT_PUBLIC_SUPABASE_URL` |+| `SUPABASE_ANON_KEY` | ✅ | Supabase anon key |+| `SUPABASE_SERVICE_ROLE_KEY` | ✅ | Service role key (used by workers and admin endpoints) |+| `OPENAI_API_KEY` | optional* | OpenAI key |+| `ANTHROPIC_API_KEY` | optional* | Anthropic key |+| `GOOGLE_GENERATIVE_AI_API_KEY` | optional* | Google Gemini key (server-side name differs from web) |+| `DEFAULT_SUGGESTION_MODEL` | optional | Default LLM for AI suggestions (default: `google/gemini-3-flash-preview`) |+| `TOPIC_SUGGESTION_MODEL` | optional | LLM for topic suggestions |+| `PROMPT_SUGGESTION_MODEL` | optional | LLM for prompt suggestions |+| `COMPETITOR_SUGGESTION_MODEL` | optional | LLM for competitor suggestions |+| `ALLOWED_ORIGINS` | ✅ | Comma-separated list of web origins allowed to call the API (for CORS) |+| `IS_CLOUD` | optional | `"true"` only for the official cloud build |+| `DATAFORSEO_LOGIN` | optional | DataForSEO login (for prompt volume analysis) |+| `DATAFORSEO_PASSWORD` | optional | DataForSEO password |+| `CLORO_API_KEY` | optional | Cloro web scraper API key (for ChatGPT/Gemini/Perplexity web scraping) |+| `PLATFORM_PROVIDER` | optional | Default `cloro`. Used to pick scraper backend |+| `AI_VOLUME_MULTIPLIER` | optional | Estimated AI search adoption rate (default `0.15` = 15% of Google volume) |+| `CRON_SECRET` | cloud only | Shared secret with web's CRON_SECRET; protects internal cron endpoints |++## Tips for production++- **Mark secrets as sensitive** — on Vercel, toggle the *Sensitive* flag on every secret env var. Once set, the value is write-only and can't be read back from the UI.+- **Rotate `SUPABASE_SERVICE_ROLE_KEY` and `CRON_SECRET`** quarterly as a hygiene practice+- **Use a different Supabase project for each environment** (dev / staging / prod). Don't share databases across environments — RLS bypasses make it easy to corrupt prod data with a misconfigured dev pointer++<Card title="Continue: Upgrading" icon="arrow-right" href="/self-host/upgrading">+ How to upgrade your self-hosted instance to a new release.+</Card>diff --git a/docs/self-host/supabase-setup.mdx b/docs/self-host/supabase-setup.mdxnew file mode 100644index 000000000..d4930e971--- /dev/null+++ b/docs/self-host/supabase-setup.mdx@@ -0,0 +1,58 @@+---+title: "Supabase setup"+description: "Prepare a Supabase project for Ansvisor — schema, RLS, auth triggers."+---++## Create the project++1. Go to [supabase.com](https://supabase.com/) and create a new project+2. Pick a region close to your server (latency matters for DB-heavy operations)+3. Save the database password somewhere safe+4. From **Project Settings → API**, copy:+ - `Project URL`+ - `anon public` key → goes into `NEXT_PUBLIC_SUPABASE_ANON_KEY` and `SUPABASE_ANON_KEY`+ - `service_role` key → goes into `SUPABASE_SERVICE_ROLE_KEY` (keep this secret — it bypasses RLS)++## Apply migrations++The repo ships SQL migrations under `supabase/migrations/`. Apply them in order:++<Tabs>+ <Tab title="Supabase CLI (recommended)">+ ```bash+ npm install -g supabase+ cd supabase+ supabase link --project-ref YOUR_PROJECT_REF+ supabase db push+ ```+ </Tab>+ <Tab title="Manual via dashboard">+ 1. Open Supabase dashboard → SQL Editor+ 2. For each file in `supabase/migrations/` (in alphabetical order), paste contents → Run+ 3. Verify all tables created under **Database → Tables**+ </Tab>+</Tabs>++## What the migrations create++- 16 tables (`organizations`, `profiles`, `brands`, `prompts`, `prompt_results`, `topics`, `competitors`, `content_opportunities`, `prompt_suggestions`, `ai_traffic_logs`, `webhook_configs`, etc.)+- RLS (Row-Level Security) policies for multi-tenant isolation by `organization_id`+- An auth trigger that auto-creates a `profile` row when a new user signs up+- The `user_role` enum (`admin`, `manager`, `analyst`, `agency_partner`)+- Index optimization for analytics-heavy queries (per-brand, per-day windows)++## Auth configuration++In Supabase dashboard → **Authentication → URL Configuration**:+- **Site URL**: your web app URL (`http://localhost:3000` for dev, `https://app.example.com` for prod)+- **Redirect URLs**: add `<site_url>/auth/callback`++Optionally enable OAuth providers (Google, GitHub) under **Authentication → Providers** if you want social sign-in.++## Storage (optional)++If you'll let users upload brand logos, create a public storage bucket called `brand-logos`. The web app handles upload/access automatically once it exists.++<Card title="Continue: Env variables" icon="arrow-right" href="/self-host/env-variables">+ Full reference for every env var in `web/.env` and `server/.env`.+</Card>diff --git a/docs/self-host/upgrading.mdx b/docs/self-host/upgrading.mdxnew file mode 100644index 000000000..c6d3f59bc--- /dev/null+++ b/docs/self-host/upgrading.mdx@@ -0,0 +1,61 @@+---+title: "Upgrading"+description: "How to safely upgrade your self-hosted Ansvisor instance."+---++## Standard upgrade++```bash+cd ansvisor+git pull+docker compose up -d --build+```++That's it for most releases. Behind the scenes:++- Docker rebuilds the changed image(s)+- `restart: unless-stopped` ensures containers come back up automatically+- Migrations under `supabase/migrations/` are forward-only — re-running `supabase db push` is idempotent++## When migrations are involved++If the release introduces new SQL migrations:++```bash+cd ansvisor+git pull+cd supabase+supabase db push # apply new migrations+cd ..+docker compose up -d --build+```++Always run migrations **before** restarting containers — new code may expect new tables/columns.++## Major version upgrades++When jumping a major version (e.g. v1 → v2), check the release notes on [GitHub Releases](https://github.com/aeohub/ansvisor/releases) for breaking changes. Common scenarios:++- Renamed env variables — update `web/.env` and `server/.env`+- Migration that requires manual data backfill — release notes will spell it out+- Removed deprecated endpoints — your custom integrations might need updates++## Rollback++If an upgrade breaks something:++```bash+cd ansvisor+git checkout v0.1.0 # previous tag+docker compose up -d --build+```++Database migrations are **not** automatically reversed. If a new migration introduced a breaking schema change, you may need to manually restore from a Supabase backup taken before the upgrade.++<Tip>+**Always take a Supabase backup before upgrading** in production. From the Supabase dashboard: Database → Backups → New backup. Free tier includes daily backups; Pro tier offers point-in-time recovery.+</Tip>++## Watching the changelog++Subscribe to release notifications on the GitHub repo: [aeohub/ansvisor → Watch → Releases only](https://github.com/aeohub/ansvisor). You'll get an email for each new release with the full changelog.