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
feat(action-center): make the visibility drop detector fire, and give Protect a trigger (#823)
Gökhan Geyik5494f6ac1010
diff --git a/server/src/config/action-engine.js b/server/src/config/action-engine.jsindex 354180114..25f58d084 100644--- a/server/src/config/action-engine.js+++ b/server/src/config/action-engine.js@@ -33,16 +33,41 @@ export const ENGINE_THRESHOLDS = Object.freeze({windowDays: 7,/**- * A visibility fall has to clear both: enough absolute points that it is- * visible on a chart, and enough of the brand's own level that it means- * something. Either alone misfires — fifteen points is catastrophic at a- * base of twenty and noise at a base of ninety.+ * A visibility fall is judged by how much of the brand's own level it+ * took, not by a fixed number of points.+ *+ * Brands sit anywhere from under 1% to 88% visible; a points threshold+ * decides which of them are allowed to have the signal at all. At 15+ * points a brand sitting at 12% could lose four fifths of its visibility+ * unreported, having never had 15 points to lose — which is why the+ * detector had not fired once in production.+ *+ * The floor exists only to clear measurement noise: week-to-week movement+ * averages 1.2 points across live brands, so 3 sits comfortably above the+ * wobble without excluding anyone. Measured across 124 brands, the pair+ * reports about four a week.*/- visibilityDropPoints: 15,visibilityDropRatio: 0.3,+ visibilityDropFloorPoints: 3,/** Below this many tracked prompts the average is too thin to trust. */visibilityDropMinPrompts: 10,+ /**+ * Early deterioration — the Protect family's trigger.+ *+ * Judged relatively like the collapse above, one band below it, so the two+ * grades are measured the same way and differ only in severity. A fixed+ * points band would have been almost empty: with the collapse at 30% of a+ * baseline, five points from a baseline of twenty leaves less than a point+ * of room between the grades.+ *+ * The baseline keeps it to brands with something to protect. Scores across+ * live brands average 9.8 and top out at 48, so ten is "above average" —+ * a real position, not a brand that was barely visible to begin with.+ */+ slippingMinRatio: 0.1,+ slippingMinBaseline: 10,+/** A competitor's rise, in points, before it is worth reporting. */competitorSurgePoints: 15,diff --git a/server/src/lib/action-center/generate.js b/server/src/lib/action-center/generate.jsindex c1381c349..2eff0db02 100644--- a/server/src/lib/action-center/generate.js+++ b/server/src/lib/action-center/generate.js@@ -49,6 +49,16 @@ const ACTION_RULES = [signalKinds: ['sharp_drop', 'lost_citations'],taskKeys: ['analyze_losses', 'coverage_gaps', 'update_content', 'internal_links', 'validate'],},+ // The Protect family's first definition. Kept apart from recover_visibility+ // on purpose: the work differs. Recovering asks what was lost and how to+ // win it back; protecting asks what is slipping and how to hold it, while+ // the position still exists to hold.+ {+ kind: 'protect_visibility',+ category: 'protect',+ signalKinds: ['visibility_slipping'],+ taskKeys: ['diagnose_slip', 'review_responses', 'reinforce_content', 'validate'],+ },{kind: 'capture_ai_traffic',category: 'growth',@@ -92,6 +102,14 @@ function buildPayload(rule, signals) {}break;}+ case 'protect_visibility': {+ const slip = (byKind.get('visibility_slipping') ?? [])[0];+ if (slip) {+ payload.dropFrom = slip.previous_value;+ payload.dropTo = slip.current_value;+ }+ break;+ }case 'capture_ai_traffic':payload.pageCount = (byKind.get('page_opportunity') ?? []).length;break;diff --git a/server/src/lib/pulse/metrics.js b/server/src/lib/pulse/metrics.jsindex 85d2e7e23..0edbbd5b2 100644--- a/server/src/lib/pulse/metrics.js+++ b/server/src/lib/pulse/metrics.js@@ -374,6 +374,43 @@ async function latestCompletedRunTimes(brandId, limit = 3) {* windows, while the detector windows (7d vs previous 7d, 14d citation* history) stay fixed per the issue spec.*/+/**+ * How far visibility fell, and which grade of signal that is.+ *+ * A brand's visible-prompt rate is whatever its own level happens to be —+ * measured across live brands it ranges from under 1% to 88% — so judging a+ * fall by a fixed number of points decides which customers are allowed to+ * have the signal at all. Requiring 15 points meant a brand sitting at 12%+ * could lose four fifths of its visibility unreported, never having had 15+ * points to lose. That is why this detector had not fired once in production.+ *+ * Severity is therefore led by the relative loss, with an absolute floor only+ * to clear measurement noise — week-to-week movement averages 1.3 points+ * across live brands, so three sits above the wobble without excluding much.+ *+ * The two grades are exclusive and ordered: a fall severe enough to be a+ * collapse is that, not an early warning. Recover asks what was lost and how+ * to win it back; Protect asks what is slipping and how to hold it while the+ * position still exists to hold.+ *+ * Returns null when nothing is worth reporting.+ */+export function classifyVisibilityFall({ from, to, promptCount, outage = false }) {+ if (outage) return null;+ if (promptCount < detection.visibilityDropMinPrompts) return null;++ const drop = round1(from - to);+ if (drop < detection.visibilityDropFloorPoints) return null;++ const relative = from > 0 ? drop / from : 0;+ if (relative >= detection.visibilityDropRatio) return { type: 'sharp_drop', drop };++ if (from >= detection.slippingMinBaseline && relative >= detection.slippingMinRatio) {+ return { type: 'visibility_slipping', drop };+ }+ return null;+}+export async function computePulseMetrics(brandId, { windowDays = 1, now = new Date() } = {}) {// Daily KPI windows anchor to the tracking-run ledger — the exact same// windows the Insights 24h view resolves (getTrackingWindow) — so the@@ -506,20 +543,19 @@ export async function computePulseMetrics(brandId, { windowDays = 1, now = new Dconst warnings = [];const outage = degraded.length > 0;- const drop = round1(prevWeekRate.rate - weekRate.rate);- if (- !outage &&- weekRate.total >= detection.visibilityDropMinPrompts &&- drop >= detection.visibilityDropPoints &&- prevWeekRate.rate > 0 &&- drop / prevWeekRate.rate >= detection.visibilityDropRatio- ) {+ const fall = classifyVisibilityFall({+ from: prevWeekRate.rate,+ to: weekRate.rate,+ promptCount: weekRate.total,+ outage,+ });+ if (fall) {warnings.push({- type: 'sharp_drop',- key: 'sharp_drop',+ type: fall.type,+ key: fall.type,from: prevWeekRate.rate,to: weekRate.rate,- drop,+ drop: fall.drop,});}diff --git a/server/src/lib/pulse/visibility-fall.test.js b/server/src/lib/pulse/visibility-fall.test.jsnew file mode 100644index 000000000..a93aca152--- /dev/null+++ b/server/src/lib/pulse/visibility-fall.test.js@@ -0,0 +1,89 @@+import { describe, expect, it, vi } from 'vitest';++// metrics.js reaches the admin client at import time, whose config hard-exits+// without SUPABASE_* env (as in CI). The classifier under test touches none+// of it — it is pure arithmetic over two numbers.+vi.mock('../../config/supabase.js', () => ({ default: { rpc: vi.fn(), from: vi.fn() } }));+vi.mock('../logger.js', () => ({+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },+}));++import { classifyVisibilityFall } from './metrics.js';+import { ENGINE_THRESHOLDS } from '../../config/action-engine.js';++const { detection } = ENGINE_THRESHOLDS;+const ENOUGH_PROMPTS = detection.visibilityDropMinPrompts;++const fall = (from, to, over = {}) =>+ classifyVisibilityFall({ from, to, promptCount: ENOUGH_PROMPTS, ...over });++describe('classifyVisibilityFall', () => {+ /**+ * The regression this whole change exists for. The rule used to demand 15+ * absolute points, so a brand whose visibility never reached 15 could lose+ * all of it and go unreported — which is why the detector had not fired+ * once in production. Scores across live brands average under 10.+ */+ it('reports a collapse at a low baseline, which a points threshold could not', () => {+ expect(fall(6.5, 2.3)).toEqual({ type: 'sharp_drop', drop: 4.2 });+ });++ it('still reports a collapse at a high baseline', () => {+ expect(fall(48, 20)).toEqual({ type: 'sharp_drop', drop: 28 });+ });++ /**+ * The noise floor. Week-to-week movement averages 1.3 points on its own;+ * without this, a brand sitting at 2.0 losing 1.0 would be filed as having+ * lost half its visibility every other week.+ */+ it('ignores a large relative loss that is only noise in absolute terms', () => {+ const noise = detection.visibilityDropFloorPoints - 0.1;+ expect(fall(3, 3 - noise)).toBeNull();+ });++ it('reports early deterioration from a position worth protecting', () => {+ const from = detection.slippingMinBaseline + 10;+ const drop = from * 0.15; // inside the band: past slipping, short of collapse+ expect(fall(from, from - drop)).toMatchObject({ type: 'visibility_slipping' });+ });++ /**+ * The two grades are exclusive and ordered. A fall severe enough to be a+ * collapse is that, not an early warning — otherwise Protect and Recover+ * would fire on the same brand for the same week.+ */+ it('grades a severe fall as a collapse, never as slipping', () => {+ const from = detection.slippingMinBaseline + 10;+ const drop = from * 0.5;+ expect(fall(from, from - drop)).toMatchObject({ type: 'sharp_drop' });+ });++ /** Protect is for brands with something to protect. The same relative slip+ * at a low base is a brand that was barely visible to begin with. */+ it('does not warn about slipping when there was no position to hold', () => {+ const from = detection.slippingMinBaseline - 1;+ const drop = from * (detection.slippingMinRatio + 0.05);+ expect(fall(from, from - drop)).toBeNull();+ });++ it('says nothing about a brand whose visibility rose', () => {+ expect(fall(10, 25)).toBeNull();+ });++ it('says nothing when too few prompts are tracked to average over', () => {+ expect(fall(40, 10, { promptCount: ENOUGH_PROMPTS - 1 })).toBeNull();+ });++ /**+ * A platform-wide collection incident makes every brand look like it+ * collapsed. Reporting that as their problem would be worse than silence.+ */+ it('stays silent during a platform outage', () => {+ expect(fall(40, 10, { outage: true })).toBeNull();+ });++ it('handles a brand that had no visibility to lose', () => {+ expect(fall(0, 0)).toBeNull();+ });+});diff --git a/server/src/lib/signals/record.js b/server/src/lib/signals/record.jsindex a76e8695b..58b6b6519 100644--- a/server/src/lib/signals/record.js+++ b/server/src/lib/signals/record.js@@ -50,6 +50,16 @@ const KIND_META = {kpiKeys: ['ai_visibility'],persistent: true,},+ // Early deterioration, the Protect family's trigger: a brand with a real+ // position losing ground, caught before it becomes the collapse above.+ // Medium rather than high — it is a warning, not an emergency, and filing+ // it as high would make both grades mean the same thing.+ visibility_slipping: {+ category: 'visibility',+ impact: 'medium',+ kpiKeys: ['ai_visibility'],+ persistent: true,+ },prompt_gain: {category: 'visibility',impact: 'medium',@@ -130,6 +140,7 @@ function fromPulseEntry(entry) {switch (entry.type) {case 'sharp_drop':+ case 'visibility_slipping':candidate.previousValue = entry.from;candidate.currentValue = entry.to;candidate.changeValue = -entry.drop;diff --git a/web/messages/en.json b/web/messages/en.jsonindex 8f0af5b3b..f4c0561c5 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -273,7 +273,8 @@"overtaken": "Overtaken","crossed": "Crossed","uncited": "Uncited",- "issue": "Issue"+ "issue": "Issue",+ "slipping": "Slipping"},"affected": {"prompts": "{count, plural, one {1 prompt} other {# prompts}}",@@ -358,6 +359,10 @@"audit_low_score": {"title": "Audited pages score low on AEO readiness","description": "{count, plural, one {1 audited page scores} other {# audited pages score}} below 50/100."+ },+ "visibility_slipping": {+ "title": "Visibility is slipping",+ "description": "You were visible in {from}% of responses, now {to}%."}},"actionCategories": {@@ -513,6 +518,12 @@"titleMany": "Close the gap with competitors","description": "Competitor visibility moved sharply against you across your tracked prompts.","goal": "Regain the visibility position lost to competitors."+ },+ "protect_visibility": {+ "title": "Protect visibility before it slips further",+ "description": "Visibility is falling from a strong position.",+ "descriptionWithDrop": "Visibility slipped from {from}% to {to}% — still strong, but heading down.",+ "goal": "Hold the position while it is still there, rather than recovering it later."}},"actionTasks": {@@ -530,7 +541,10 @@"fix_issues": "Fix the highest-impact issues first","revalidate": "Re-run the audits to confirm the fixes","analyze_competitor": "Analyze what the competitor gained visibility with",- "strengthen_content": "Strengthen your content where they now win"+ "strengthen_content": "Strengthen your content where they now win",+ "diagnose_slip": "Diagnose what changed in the last week",+ "review_responses": "Review the AI responses that stopped mentioning you",+ "reinforce_content": "Reinforce the content behind the affected prompts"},"taskStatus": {"todo": "To Do",diff --git a/web/src/components/action-center/action-table.tsx b/web/src/components/action-center/action-table.tsxindex 716c21cb0..c873bcfae 100644--- a/web/src/components/action-center/action-table.tsx+++ b/web/src/components/action-center/action-table.tsx@@ -1,7 +1,14 @@'use client';import { useTranslations } from 'next-intl';-import { BarChart3, MessageSquare, MousePointerClick, Swords, Wrench } from 'lucide-react';+import {+ BarChart3,+ MessageSquare,+ MousePointerClick,+ Swords,+ Wrench,+ ShieldCheck,+} from 'lucide-react';import { Badge } from '@/components/ui/badge';import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';import {@@ -21,6 +28,7 @@ import { cn } from '@/lib/utils';export const KIND_ICONS: Record<ActionKind, React.ComponentType<{ className?: string }>> = {recover_visibility: BarChart3,+ protect_visibility: ShieldCheck,capture_ai_traffic: MousePointerClick,convert_mentions: MessageSquare,fix_low_scores: Wrench,diff --git a/web/src/components/action-center/signal-table.tsx b/web/src/components/action-center/signal-table.tsxindex e6cac7306..e72f0caa3 100644--- a/web/src/components/action-center/signal-table.tsx+++ b/web/src/components/action-center/signal-table.tsx@@ -49,6 +49,7 @@ import { cn } from '@/lib/utils';export const SIGNAL_ICONS: Record<SignalKind, React.ComponentType<{ className?: string }>> = {sharp_drop: TrendingDown,+ visibility_slipping: TrendingDown,prompt_gain: TrendingUp,new_engine: Sparkles,lost_citations: Unlink,diff --git a/web/src/lib/action-center/display.ts b/web/src/lib/action-center/display.tsindex 41d7c0eb5..72ae703b9 100644--- a/web/src/lib/action-center/display.ts+++ b/web/src/lib/action-center/display.ts@@ -32,6 +32,18 @@ export function actionTexts(: t('recover_visibility.description', { prompts: num(p, 'promptCount') }),};}+ case 'protect_visibility': {+ const hasDrop = p.dropFrom !== undefined && p.dropFrom !== null;+ return {+ title: t('protect_visibility.title'),+ description: hasDrop+ ? t('protect_visibility.descriptionWithDrop', {+ from: num(p, 'dropFrom'),+ to: num(p, 'dropTo'),+ })+ : t('protect_visibility.description'),+ };+ }case 'capture_ai_traffic':return {title: t('capture_ai_traffic.title', { pages: num(p, 'pageCount') }),@@ -69,6 +81,8 @@ export function actionContextTags(action: ActionItem, t: Translator): string[] {case 'recover_visibility':if (num(p, 'promptCount') > 0) tags.push(t('tags.prompts', { count: num(p, 'promptCount') }));break;+ case 'protect_visibility':+ break;case 'capture_ai_traffic':tags.push(t('tags.pages', { count: num(p, 'pageCount') }));break;diff --git a/web/src/lib/action-center/registry.ts b/web/src/lib/action-center/registry.tsindex c34475792..20cb0b784 100644--- a/web/src/lib/action-center/registry.ts+++ b/web/src/lib/action-center/registry.ts@@ -31,6 +31,7 @@ export type ActionOutcome =export type ActionKind =| 'recover_visibility'+ | 'protect_visibility'| 'capture_ai_traffic'| 'convert_mentions'| 'fix_low_scores'@@ -96,6 +97,10 @@ export const ACTION_KINDS: Record<ActionKind, ActionKindMeta> = {kind: 'recover_visibility',taskKeys: ['analyze_losses', 'coverage_gaps', 'update_content', 'internal_links', 'validate'],},+ protect_visibility: {+ kind: 'protect_visibility',+ taskKeys: ['diagnose_slip', 'review_responses', 'reinforce_content', 'validate'],+ },capture_ai_traffic: {kind: 'capture_ai_traffic',taskKeys: ['review_pages', 'coverage_gaps', 'optimize_content', 'validate'],diff --git a/web/src/lib/signals/display.ts b/web/src/lib/signals/display.tsindex 96ac079a6..455bfc42c 100644--- a/web/src/lib/signals/display.ts+++ b/web/src/lib/signals/display.ts@@ -19,6 +19,7 @@ export function signalTexts(signal: Signal, t: Translator): { title: string; desconst values = ((): Record<string, string | number> => {switch (signal.kind) {case 'sharp_drop':+ case 'visibility_slipping':return { from: signal.previousValue ?? 0, to: signal.currentValue ?? 0 };case 'prompt_gain':return { prompt: str(p, 'promptText'), gain: signal.changeValue ?? 0 };@@ -68,6 +69,7 @@ export function signalAffected(const p = signal.payload;switch (signal.kind) {case 'sharp_drop':+ case 'visibility_slipping':return { label: t('affected.allPrompts'), detail: null };case 'prompt_gain':case 'lost_citations':diff --git a/web/src/lib/signals/registry.ts b/web/src/lib/signals/registry.tsindex 9f2057cae..3da3ea8e5 100644--- a/web/src/lib/signals/registry.ts+++ b/web/src/lib/signals/registry.ts@@ -25,6 +25,7 @@ export type SignalStatus = 'new' | 'acknowledged' | 'resolved' | 'dismissed';export type SignalKind =| 'sharp_drop'+ | 'visibility_slipping'| 'prompt_gain'| 'new_engine'| 'lost_citations'@@ -71,6 +72,7 @@ export interface SignalKindMeta {| 'overtaken'| 'crossed'| 'uncited'+ | 'slipping'| 'issue';/** Whether the change arrow, when change_value is present, is good news. */positive: boolean;@@ -78,6 +80,7 @@ export interface SignalKindMeta {export const SIGNAL_KINDS: Record<SignalKind, SignalKindMeta> = {sharp_drop: { kind: 'sharp_drop', stateKey: 'dropped', positive: false },+ visibility_slipping: { kind: 'visibility_slipping', stateKey: 'slipping', positive: false },prompt_gain: { kind: 'prompt_gain', stateKey: 'gained', positive: true },new_engine: { kind: 'new_engine', stateKey: 'gained', positive: true },lost_citations: { kind: 'lost_citations', stateKey: 'lost', positive: false },