Skip to content

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

feat(prompts): show Improve what the cited competitor pages have that the brand's page doesn't (learning C2) (#1724)

Cihan0ae7830da199
diff --git a/docs/guides/prompts.mdx b/docs/guides/prompts.mdx
index 0e195ea6c..b5b9943a5 100644
--- a/docs/guides/prompts.mdx
+++ b/docs/guides/prompts.mdx
@@ -291,6 +291,8 @@ If a draft that isn't published yet already covers the prompt — one started fr
The tab's suggestions per platform are written from the answers' evidence and from this brand's last two Improve actions on the prompt for the same region: which of their suggestions were done or skipped, and how each platform moved since. They build on what moved, and don't suggest again what was done on a platform that didn't, or what your team skipped. An action sent less than a week ago is too early to tell either way. Only this brand's own actions are read.
+When the Action Center's **Analyze competitor content** has read the pages cited for the prompt in the last month, the tab's suggestions also see what Site Audit's checks found on them: which checks each competitor page passes, and which they have that your cited page doesn't. They build on what was seen there, not a guess.
+
## Best practices
- Aim for **20–80 active prompts** per brand. Below 20 you miss coverage; above 80 noise drowns insights.
diff --git a/server/src/lib/action-center/competitor-pages.js b/server/src/lib/action-center/competitor-pages.js
index 251cb36d7..6f41923ca 100644
--- a/server/src/lib/action-center/competitor-pages.js
+++ b/server/src/lib/action-center/competitor-pages.js
@@ -350,3 +350,29 @@ export async function analyzeCompetitorPages({
unreadable,
};
}
+
+/**
+ * What the checks found on pages already read (learning C2), by page key,
+ * for the brand: read in the last two `freshDays`, never read here. Improve
+ * gives them to its model as seen evidence, not a guess.
+ *
+ * @returns {Promise<Map<string, { own: boolean, checks: Record<string, string> }>>}
+ */
+export async function storedFeatures(brandId, urls, now = new Date()) {
+ const keys = [...new Set(urls.map((url) => opportunityKey(url)).filter(Boolean))];
+ if (keys.length === 0) return new Map();
+ const since = new Date(now.getTime() - 2 * C.freshDays * DAY_MS).toISOString();
+ const { data, error } = await supabaseAdmin
+ .from('cited_page_features')
+ .select('page_key, own, features')
+ .eq('brand_id', brandId)
+ .in('page_key', keys)
+ .gte('read_at', since);
+ if (error) throw new Error(error.message);
+ return new Map(
+ (data ?? [])
+ // A page that couldn't be read leaves a row with nothing to tell.
+ .filter((row) => !row.features?.unreadable && row.features?.checks)
+ .map((row) => [row.page_key, { own: row.own === true, checks: row.features.checks }]),
+ );
+}
diff --git a/server/src/lib/action-center/competitor-pages.test.js b/server/src/lib/action-center/competitor-pages.test.js
index 66a468ea5..a4a9d4a5e 100644
--- a/server/src/lib/action-center/competitor-pages.test.js
+++ b/server/src/lib/action-center/competitor-pages.test.js
@@ -22,7 +22,7 @@ vi.mock('../../config/supabase.js', () => ({
eq: (column, value) => (op.filters.push(['eq', column, value]), chain),
neq: () => chain,
in: (column, value) => (op.filters.push(['in', column, value]), chain),
- gte: () => chain,
+ gte: (column, value) => (op.filters.push(['gte', column, value]), chain),
order: () => chain,
limit: () => chain,
upsert: async (row) => (writes.push(row), { error: upsertError }),
@@ -49,6 +49,7 @@ const {
pageFeatures,
robotsDisallow,
scopePromptIds,
+ storedFeatures,
} = await import('./competitor-pages.js');
const pure = await import('./page-features.js');
@@ -413,3 +414,31 @@ describe('analyzeCompetitorPages', () => {
expect(noPrompts).toMatchObject({ retryDays: 7, output: { reason: 'no_prompts' } });
});
});
+
+/** What the checks found on pages read lately, for Improve (learning C2). */
+describe('storedFeatures', () => {
+ it('reads the pages read lately by key, leaving out one that could not be read', async () => {
+ tables.cited_page_features = [
+ { page_key: 'rival.com/kettles', own: false, features: { checks: { tables: 'pass' } } },
+ { page_key: 'blog.example/best', own: false, features: { unreadable: true } },
+ ];
+ const stored = await storedFeatures(
+ 'b1',
+ ['https://www.rival.com/kettles/', 'https://blog.example/best'],
+ NOW,
+ );
+ expect([...stored.entries()]).toEqual([
+ ['rival.com/kettles', { own: false, checks: { tables: 'pass' } }],
+ ]);
+ // The brand's own reads only, from the last two freshDays (28 days).
+ const read = queries.find((q) => q.table === 'cited_page_features');
+ expect(read.filters).toContainEqual(['eq', 'brand_id', 'b1']);
+ expect(read.filters).toContainEqual([
+ 'in',
+ 'page_key',
+ ['rival.com/kettles', 'blog.example/best'],
+ ]);
+ expect(read.filters).toContainEqual(['gte', 'read_at', '2026-09-30T03:00:00.000Z']);
+ expect(await storedFeatures('b1', [])).toEqual(new Map());
+ });
+});
diff --git a/server/src/lib/prompt-improve.js b/server/src/lib/prompt-improve.js
index 7e1b9dbb5..8d568e534 100644
--- a/server/src/lib/prompt-improve.js
+++ b/server/src/lib/prompt-improve.js
@@ -2,7 +2,9 @@
* Positions panel → Improve tab (PROMPT-003): platform-specific suggestions to
* improve one prompt's position.
*
- * Pure on purpose. The route loads the answers; this module decides each
+ * Pure on purpose. The route loads the answers, and what the page checks
+ * found on the cited pages lately (storedFeatures); this module, which reads
+ * no database (page-features.js, not competitor-pages.js), decides each
* platform's state, gathers the evidence the model may cite, builds the
* prompt, and checks what comes back against that evidence. The checks are
* the point of the feature: a suggestion has to name a real sub-query, URL or
@@ -11,6 +13,9 @@
import { z } from 'zod';
import { extractHostname } from './response-parser.js';
+import { FEATURE_CHECKS, featureGaps } from './action-center/page-features.js';
+import { describeSignal } from './audit/rubric.js';
+import { opportunityKey } from './audit/opportunities.js';
/** Labels for the engines the Positions panel lists (web/src/lib/prompt-positions.ts). */
export const IMPROVE_PLATFORM_LABELS = {
@@ -323,6 +328,17 @@ function evidenceBlock(evidence) {
if (evidence.brandPages.length) {
lines.push(`Brand pages cited: ${evidence.brandPages.map((u) => u.url).join(' ; ')}`);
}
+ // What Site Audit's checks found on those pages, read lately (learning C2).
+ if (evidence.pageChecks?.length) {
+ lines.push(
+ `Checks on these pages (Site Audit, read lately): ${evidence.pageChecks
+ .map((p) => `${p.url}${p.own ? ' (brand)' : ''}: ${p.passes.join(', ') || 'none of them'}`)
+ .join(' ; ')}`,
+ );
+ }
+ if (evidence.checkGaps?.length) {
+ lines.push(`The competitor pages have and the brand's don't: ${evidence.checkGaps.join(', ')}`);
+ }
if (evidence.excerpt) lines.push(`Latest AI answer (excerpt): """${evidence.excerpt}"""`);
return lines.map((l) => ` ${l}`).join('\n');
}
@@ -387,6 +403,46 @@ Build on suggestions that came before an improvement on their platform. Do not s
}${skipped ? ' Do not suggest again what the team skipped.' : ''}`;
}
+/**
+ * A platform's evidence with what Site Audit's checks found on its cited
+ * pages, where they were read lately (learning C2): each page's passing
+ * checks by name, and the checks most of the competitor pages pass that
+ * the brand's cited page doesn't. Unchanged when none was read.
+ *
+ * @param {object} evidence as collectEvidence gives it
+ * @param {Map<string, { own: boolean, checks: Record<string, string> }>} stored storedFeatures'
+ */
+export function withPageChecks(evidence, stored) {
+ if (!stored?.size) return evidence;
+ // collectEvidence counts addresses: one page cited under two (www,
+ // tracking parameters) is one page here, its first address kept, or it
+ // would count twice toward featureGaps' two pages at least.
+ const seen = new Set();
+ const read = [
+ ...evidence.competitorUrls.map((u) => ({ url: u.url, own: false })),
+ ...evidence.brandPages.map((u) => ({ url: u.url, own: true })),
+ ].flatMap((page) => {
+ const key = opportunityKey(page.url);
+ const found = stored.get(key);
+ if (!found || seen.has(key)) return [];
+ seen.add(key);
+ return [{ ...page, checks: found.checks }];
+ });
+ if (!read.length) return evidence;
+ const name = (key) => describeSignal(key)?.label ?? key;
+ const theirs = read.filter((p) => !p.own);
+ const ours = read.find((p) => p.own) ?? null;
+ return {
+ ...evidence,
+ pageChecks: read.map((p) => ({
+ url: p.url,
+ own: p.own,
+ passes: FEATURE_CHECKS.filter((key) => p.checks[key] === 'pass').map(name),
+ })),
+ checkGaps: ours && theirs.length ? featureGaps(theirs, ours).map((gap) => gap.label) : [],
+ };
+}
+
/**
* System and user prompt for one generation. `platforms` are the actionable
* ones: [{ id, state, mentionPosition, mentionTotal, citationRank, evidence }].
diff --git a/server/src/lib/prompt-improve.test.js b/server/src/lib/prompt-improve.test.js
index fc141d4cc..67900dc22 100644
--- a/server/src/lib/prompt-improve.test.js
+++ b/server/src/lib/prompt-improve.test.js
@@ -7,6 +7,7 @@ import {
improveRangeKey,
isKnownSource,
sanitizeSuggestions,
+ withPageChecks,
} from './prompt-improve.js';
const BRAND_DOMAINS = ['acme.com'];
@@ -493,3 +494,71 @@ describe('Improve plan limits', () => {
expect(PLANS.self_hosted.limits.improveMonthlyBudgetUsd).toBe(-1);
});
});
+
+/** What Site Audit's checks found on the cited pages, read lately (learning C2). */
+describe('withPageChecks', () => {
+ const evidence = {
+ fanouts: [],
+ citedDomains: [],
+ competitors: [],
+ competitorUrls: [
+ { url: 'https://rival.com/kettles', count: 3 },
+ { url: 'https://other-rival.com/best-kettles', count: 2 },
+ ],
+ brandPages: [{ url: 'https://acme.com/kettles', count: 1 }],
+ excerpt: '',
+ };
+ const stored = new Map([
+ ['rival.com/kettles', { own: false, checks: { 'faq-schema': 'pass', tables: 'pass' } }],
+ ['other-rival.com/best-kettles', { own: false, checks: { 'faq-schema': 'pass' } }],
+ ['acme.com/kettles', { own: true, checks: { tables: 'pass' } }],
+ ]);
+
+ it('names what each page passes and what theirs have that the brand page lacks', () => {
+ const shown = withPageChecks(evidence, stored);
+ expect(shown.pageChecks.map((p) => [p.url, p.own, p.passes.length])).toEqual([
+ ['https://rival.com/kettles', false, 2],
+ ['https://other-rival.com/best-kettles', false, 1],
+ ['https://acme.com/kettles', true, 1],
+ ]);
+ // Compared over two competitor pages at least (C1): FAQ schema on both,
+ // not on the brand's.
+ expect(shown.checkGaps).toHaveLength(1);
+
+ const { prompt } = buildImprovePrompt({
+ promptText: 'best kettle',
+ brand: { name: 'Acme', domains: [] },
+ platforms: [{ id: 'gemini-web', state: 'not_mentioned', evidence: shown }],
+ });
+ expect(prompt).toContain(
+ 'Checks on these pages (Site Audit, read lately): https://rival.com/kettles: ',
+ );
+ expect(prompt).toContain("The competitor pages have and the brand's don't: ");
+ });
+
+ it('counts one page cited under two addresses once, at the first', () => {
+ const shown = withPageChecks(
+ {
+ ...evidence,
+ competitorUrls: [
+ { url: 'https://rival.com/kettles', count: 3 },
+ { url: 'https://www.rival.com/kettles?utm_source=chatgpt.com', count: 2 },
+ ],
+ },
+ stored,
+ );
+ expect(shown.pageChecks.map((p) => p.url)).toEqual([
+ 'https://rival.com/kettles',
+ 'https://acme.com/kettles',
+ ]);
+ // One competitor page is too few to compare (C1): no gap.
+ expect(shown.checkGaps).toEqual([]);
+ });
+
+ it('leaves the evidence as it was when none of its pages was read', () => {
+ expect(withPageChecks(evidence, new Map())).toBe(evidence);
+ expect(withPageChecks(evidence, new Map([['other.com/x', { own: false, checks: {} }]]))).toBe(
+ evidence,
+ );
+ });
+});
diff --git a/server/src/routes/prompts-improve-page-checks.test.js b/server/src/routes/prompts-improve-page-checks.test.js
new file mode 100644
index 000000000..deadb1a6d
--- /dev/null
+++ b/server/src/routes/prompts-improve-page-checks.test.js
@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+
+/**
+ * POST /api/prompts/:promptId/improve gives its model what Site Audit's
+ * checks found on the cited pages lately (learning C2). A read of them that
+ * fails goes without them rather than failing the build, and says so in the
+ * log.
+ */
+
+const storedFeatures = vi.fn();
+const warn = vi.fn();
+
+function table(name) {
+ const result = () => {
+ if (name === 'prompts') {
+ return { data: { id: 'p1', text: 'best crm', prompt_sets: { brand_id: 'b1' } }, error: null };
+ }
+ if (name === 'brands') return { data: { id: 'b1', organization_id: 'o1' }, error: null };
+ if (name === 'profiles') return { data: { organization_id: 'o1' }, error: null };
+ if (name === 'prompt_improve_suggestions') {
+ return {
+ data: { range_key: '7d', region: '', platform_states: [], suggestions: [] },
+ error: null,
+ };
+ }
+ return { data: [], error: null };
+ };
+ const chain = new Proxy(
+ {},
+ {
+ get: (_t, prop) => {
+ if (prop === 'then') {
+ return (resolve, reject) => Promise.resolve(result()).then(resolve, reject);
+ }
+ if (prop === 'single' || prop === 'maybeSingle') return async () => result();
+ return () => chain;
+ },
+ },
+ );
+ return chain;
+}
+
+vi.mock('../config/supabase.js', () => ({ default: { from: (name) => table(name) } }));
+vi.mock('../lib/plan-guard.js', () => ({
+ PlanLimitError: class extends Error {},
+ enforceFeature: vi.fn(),
+ reserveAiBudget: vi.fn(),
+ getImproveQuotaStatus: async () => ({ unlimited: true }),
+ requireFeature: () => (_req, _res, next) => next(),
+ reserveRelevanceAllowance: vi.fn(),
+ settleRelevanceUsage: vi.fn(),
+}));
+vi.mock('../lib/action-center/competitor-pages.js', async (importOriginal) => ({
+ ...(await importOriginal()),
+ storedFeatures: (...args) => storedFeatures(...args),
+}));
+
+const { default: router } = await import('./prompts.js');
+
+let server;
+let baseUrl;
+
+beforeEach(async () => {
+ storedFeatures.mockReset();
+ warn.mockReset();
+ const app = express();
+ app.use(express.json());
+ app.use((req, _res, next) => {
+ req.user = { id: 'u1' };
+ req.log = { error: vi.fn(), info: vi.fn(), warn };
+ next();
+ });
+ app.use('/api/prompts', router);
+ await new Promise((resolve) => {
+ server = app.listen(0, resolve);
+ });
+ baseUrl = `http://127.0.0.1:${server.address().port}/api/prompts`;
+});
+
+afterEach(async () => {
+ await new Promise((resolve) => server.close(resolve));
+});
+
+describe('POST /api/prompts/:promptId/improve', () => {
+ it("goes without the page checks when they can't be read, and logs why", async () => {
+ const down = new Error('cited_page_features down');
+ storedFeatures.mockRejectedValue(down);
+ const res = await fetch(`${baseUrl}/p1/improve`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ preset: '7d', from: '2026-10-06T00:00:00.000Z' }),
+ });
+ expect(res.status).toBe(200);
+ expect(storedFeatures).toHaveBeenCalledWith('b1', []);
+ expect(warn).toHaveBeenCalledWith(
+ { err: down, promptId: 'p1' },
+ 'prompt improve page checks read failed',
+ );
+ });
+});
diff --git a/server/src/routes/prompts.js b/server/src/routes/prompts.js
index 5cd92b10e..59c13f4a8 100644
--- a/server/src/routes/prompts.js
+++ b/server/src/routes/prompts.js
@@ -34,7 +34,9 @@ import {
improveRangeKey,
improveSchema,
sanitizeSuggestions,
+ withPageChecks,
} from '../lib/prompt-improve.js';
+import { storedFeatures } from '../lib/action-center/competitor-pages.js';
import {
liveImproveSends,
loadImproveRounds,
@@ -1233,7 +1235,7 @@ router.post('/:promptId/improve', requireFeature('prompt_improve'), async (req,
: { data: [] };
const responseById = new Map((responses ?? []).map((r) => [r.id, r.response]));
- const withEvidence = actionable.map((p) => ({
+ const collected = actionable.map((p) => ({
...p,
evidence: collectEvidence(evidenceByPlatform.get(p.id) ?? [], {
brandName: brand.name,
@@ -1242,6 +1244,23 @@ router.post('/:promptId/improve', requireFeature('prompt_improve'), async (req,
latestResponse: responseById.get(byPlatform.get(p.id)[0].id),
}),
}));
+ // What Site Audit's checks found on the cited pages, where Analyze
+ // competitor content read them lately (learning C2). None read: as before.
+ // A read that fails goes without them, said in the log.
+ const stored = await storedFeatures(
+ brandId,
+ collected.flatMap((p) => [
+ ...p.evidence.competitorUrls.map((u) => u.url),
+ ...p.evidence.brandPages.map((u) => u.url),
+ ]),
+ ).catch((err) => {
+ req.log.warn({ err, promptId }, 'prompt improve page checks read failed');
+ return new Map();
+ });
+ const withEvidence = collected.map((p) => ({
+ ...p,
+ evidence: withPageChecks(p.evidence, stored),
+ }));
const modelId = improveModelId();
let suggestions = [];