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(content): have the Content Agent write from the kept sources and name them (CE-033, server) (#1398)

Cihanb2fff015a96a
diff --git a/server/src/lib/content-agent.js b/server/src/lib/content-agent.js
index 4326073a7..35c6d4d0e 100644
--- a/server/src/lib/content-agent.js
+++ b/server/src/lib/content-agent.js
@@ -4,9 +4,22 @@ import * as cheerio from 'cheerio';
import { z } from 'zod';
import supabaseAdmin from '../config/supabase.js';
import { resolveModel } from './ai-provider.js';
-import { contentBriefModelId } from './content-brief.js';
+import { contentBriefModelId, rebuildSources } from './content-brief.js';
import { linkAllowList, linkKey, linkTargetsPrompt, readLinkTargets } from './content-links.js';
import { pageTypeFormat } from './content-page-types.js';
+import {
+ SOURCES_RULE,
+ htmlText,
+ knownNumbers,
+ marksField,
+ numberSources,
+ sourceSuggestion,
+ sourcesField,
+ sourcesPrompt,
+ stripSourceIds,
+ textPieces,
+ todayText,
+} from './content-sources.js';
import { getLanguageName } from './languages.js';
import { reserveAiBudget } from './plan-guard.js';
@@ -16,8 +29,10 @@ import { reserveAiBudget } from './plan-guard.js';
* leaves suggestions for a person to review (content_draft_suggestions,
* 00217) — never changes to the page itself. A suggestion replaces words in
* one passage, or adds blocks after one, and names the rules it fixes. The
- * passages AI answers quote today (locked, CE-018) are never changed. It is
- * metered from the organization's AI usage, as the brief is.
+ * passages AI answers quote today (locked, CE-018) are never changed. It
+ * writes from the sources the Sources tab keeps and says which each change
+ * used (v1.1 CE-033, content-sources.js). It is metered from the
+ * organization's AI usage, as the brief is.
*/
/** The most suggestions one run leaves. */
@@ -81,6 +96,8 @@ export const fixRulesInput = z.object({
textRules: z.array(z.string().trim().min(1).max(300)).max(50).default([]),
/** The locked passages, by passageKey. */
locked: z.array(z.string().max(5000)).max(500).default([]),
+ /** The sources the Sources tab keeps (v1.1 CE-033); none from an older editor. */
+ sources: rebuildSources.optional(),
});
export const suggestionsSchema = z.object({
@@ -104,6 +121,8 @@ export const suggestionsSchema = z.object({
),
reason: z.string().describe('What the change does, in a few words.'),
rules: z.array(z.string()).describe('The keys of the rules it fixes.'),
+ sources: sourcesField,
+ marks: marksField,
}),
)
.max(MAX_AGENT_SUGGESTIONS),
@@ -119,7 +138,8 @@ ${HEADING_RULE}
${LINK_RULE}
${FANOUT_RULE}
- Never change a passage marked LOCKED: AI assistants quote its wording today. You may insert after it.
-- Use only facts from the page and the brand. Never invent numbers, prices, dates, names, sources or quotes. When a rule needs a fact you don't have, write a placeholder in square brackets, e.g. [figure, source, year].
+- Use only facts from the page, the brand and your data. Never invent numbers, prices, dates, names, sources or quotes. When a rule needs a fact you don't have, write a placeholder in square brackets, e.g. [figure, source, year].
+${SOURCES_RULE}
- Keep the page's voice and change as little as each rule needs. At most ${MAX_AGENT_SUGGESTIONS} suggestions.
- "reason" says in a few words what the change does and why, e.g. "add a dated data point (rule)".
- Write in the language asked for.`;
@@ -338,15 +358,24 @@ export function splitReplace(after, tag, links = null) {
* one that would still grow a heading past its headingLimit (a long heading
* may still be shortened), or make it ask a second question, is dropped.
* Links stay only to the URLs in `links` (linkAllowList): a replace's go in
- * after_links, by offset into its words, an insert's in its HTML.
+ * after_links, by offset into its words, an insert's in its HTML. Each keeps
+ * the sources it names and the words each supports (withSources); one that
+ * adds a number with no source is not kept. `sourcing` is the numbered
+ * sources and the numbers known already (the page's, the brand's): without
+ * it, the page's.
*/
-export function keepSuggestions(raw, passages, lockedKeys, ruleKeys, links = null) {
+export function keepSuggestions(raw, passages, lockedKeys, ruleKeys, links = null, sourcing = {}) {
+ const numbered = sourcing.numbered ?? [];
+ const known = sourcing.known ?? knownNumbers(...passages.map((p) => p.text));
const kept = [];
const seen = new Set();
- for (const s of raw) {
+ for (const answer of raw) {
if (kept.length >= MAX_AGENT_SUGGESTIONS) break;
+ // Source numbers belong in "sources", never in the words.
+ const s = { ...answer, after: stripSourceIds(answer.after) };
const passage = passages[s.passage - 1];
- const reason = s.reason.trim().slice(0, 300);
+ // The card shows it: a source number the model wrote in ("(S2)") goes.
+ const reason = stripSourceIds(s.reason).trim().slice(0, 300);
if (!passage || !reason || passage.text.length > MAX_PASSAGE_CHARS) continue;
const rules = [...new Set(s.rules.filter((key) => ruleKeys.has(key)))];
const insertOf = (html) =>
@@ -404,14 +433,41 @@ export function keepSuggestions(raw, passages, lockedKeys, ruleKeys, links = nul
changes = changes.filter(Boolean);
if (!changes.length || changes.some((c) => seen.has(c.id))) continue;
if (kept.length + changes.length > MAX_AGENT_SUGGESTIONS) continue;
- for (const c of changes) {
+ // What it used (v1.1 CE-033), and no number without a source.
+ const rows = changes.map((c) => withSources(c.row, s, numbered, known));
+ if (rows.some((row) => !row)) continue;
+ changes.forEach((c, i) => {
seen.add(c.id);
- kept.push(c.row);
- }
+ kept.push(rows[i]);
+ });
}
return kept;
}
+/**
+ * A change row with the sources its suggestion names and the marks on its
+ * words (a replace's after_text, an insert's HTML read as text); null when
+ * it adds a number neither the page nor a source has (sourceSuggestion).
+ */
+function withSources(row, suggestion, numbered, known) {
+ const pieces =
+ row.kind === 'replace' ? [{ text: row.after_text, start: 0 }] : textPieces(row.after_text);
+ const sourced = sourceSuggestion({
+ named: suggestion.sources,
+ marks: suggestion.marks,
+ pieces,
+ numbered,
+ known,
+ });
+ if (!sourced) return null;
+ const { sources, marks } = sourced;
+ return {
+ ...row,
+ ...(sources.length ? { sources } : {}),
+ ...(marks.length ? { source_marks: marks } : {}),
+ };
+}
+
/**
* The passages the model reads: the ones it may change (up to
* MAX_PASSAGE_CHARS each), in order, until MAX_PROMPT_PASSAGE_CHARS.
@@ -440,6 +496,7 @@ export function buildFixPrompt({
lockedKeys,
input,
linkTargets = '',
+ sources = '',
}) {
const lines = passages.map((p, i) => {
const locked = lockedKeys.has(passageKey(p.text)) ? ', LOCKED' : '';
@@ -457,13 +514,29 @@ Page type: ${pageTypeFormat(draft.page_type)}
Rules the page doesn't meet yet (key: rule — what it asks and how the page reads now):
${rules.join('\n')}
-${own.length ? `\nThe writer's own rules, to follow in every change:\n${own.join('\n')}\n` : ''}${linkTargets ? `\n${linkTargets}\n` : ''}
+${own.length ? `\nThe writer's own rules, to follow in every change:\n${own.join('\n')}\n` : ''}${sources ? `\n${sources}\n` : ''}${linkTargets ? `\n${linkTargets}\n` : ''}
The page, passage by passage:
${lines.join('\n')}
Write in ${getLanguageName(brand?.language)}.`;
}
+/**
+ * The brand's prompts among `ids`, { id, text }, in the order asked: through
+ * the prompt's set, not its topic (a prompt may have no topic).
+ */
+export async function readPrompts(brandId, ids) {
+ if (!ids.length) return [];
+ const { data, error } = await supabaseAdmin
+ .from('prompts')
+ .select('id, text, prompt_sets!inner(brand_id)')
+ .in('id', ids)
+ .eq('prompt_sets.brand_id', brandId);
+ if (error) throw error;
+ const byId = new Map((data ?? []).map((p) => [p.id, p.text]));
+ return ids.filter((id) => byId.has(id)).map((id) => ({ id, text: byId.get(id) }));
+}
+
/**
* Whether the draft's latest batch still has suggestions nobody decided:
* the editor shows only that batch, so a new one would hide them (and Undo
@@ -544,6 +617,23 @@ export async function fixDraftRules({ draftId, brandId, input }) {
const modelId = contentBriefModelId();
const lockedKeys = new Set(input.locked.map(passageKey));
const ruleKeys = new Set(input.rules.map((r) => r.key));
+ // The data it writes from, numbered; the numbers it may write unmarked.
+ const numbered = numberSources({
+ prompts: await readPrompts(brandId, input.sources?.promptIds ?? []),
+ fanouts: input.sources?.fanouts,
+ pages: input.sources?.pages,
+ queries: input.sources?.queries,
+ });
+ const known = knownNumbers(
+ htmlText(draft.body_html),
+ draft.title,
+ brand.name,
+ brand.industry,
+ brand.description,
+ ...input.rules.flatMap((r) => [r.name, r.detail]),
+ ...input.textRules,
+ todayText(),
+ );
// Where it may link: the brand's pages and the draft's sources (A).
const targets = await readLinkTargets({
brandId,
@@ -571,6 +661,7 @@ export async function fixDraftRules({ draftId, brandId, input }) {
lockedKeys,
input,
linkTargets: linkTargetsPrompt(targets, ruleKeys),
+ sources: sourcesPrompt(numbered),
}),
abortSignal: AbortSignal.timeout(CALL_TIMEOUT_MS),
});
@@ -592,6 +683,7 @@ export async function fixDraftRules({ draftId, brandId, input }) {
lockedKeys,
ruleKeys,
linkAllowList(targets),
+ { numbered, known },
);
if (!rows.length) return { count: 0, batchId: null };
diff --git a/server/src/lib/content-agent.test.js b/server/src/lib/content-agent.test.js
index 270decbb2..e869ab2fe 100644
--- a/server/src/lib/content-agent.test.js
+++ b/server/src/lib/content-agent.test.js
@@ -21,7 +21,9 @@ vi.mock('../config/supabase.js', () => ({
const chain = {
select: () => chain,
eq: () => chain,
+ in: () => chain,
order: () => chain,
+ then: (resolve) => resolve(result()),
limit: async () => result(),
insert: async (value) => (writes.push({ table, value }), { error: null }),
maybeSingle: async () => result(),
@@ -68,6 +70,7 @@ const {
splitReplace,
} = await import('./content-agent.js');
const { linkKey, NO_LINK_TARGETS } = await import('./content-links.js');
+const { knownNumbers, numberSources } = await import('./content-sources.js');
const { PlanLimitError } = await import('./plan-guard.js');
// The real hold: self-hosted here, so it reserves nothing and writes each charge.
const realGuard = await vi.importActual('./plan-guard.js');
@@ -90,12 +93,26 @@ const suggestion = (over = {}) => ({
kind: 'replace',
passage: 4,
before: 'good coffee and hot water',
- after: '15 g of coffee and 250 g of water at 94 °C ([source, year])',
+ after: 'a 1:16 ratio of freshly ground coffee to hot water ([source, year])',
reason: 'add a dated data point (rule)',
rules: ['dated', 'made-up'],
+ // Its words from the cited page, S2; its 1:16 is the fan-out's own (CE-033).
+ sources: ['S2'],
+ marks: [{ words: 'freshly ground coffee', source: 'S2' }],
...over,
});
+/** The sources an editor keeps, numbered as the agent reads them: a fan-out (S1), a cited page (S2). */
+const SOURCES = {
+ promptIds: [],
+ fanouts: [{ query: 'Pour over ratio 1:16', platforms: ['chatgpt'] }],
+ pages: [{ url: 'https://sca.example/brew', kind: 'publication' }],
+ queries: [],
+ headings: [],
+ length: 3000,
+};
+const sourcing = { numbered: numberSources(SOURCES) };
+
beforeEach(() => {
writes = [];
rows = {
@@ -175,19 +192,90 @@ describe('keepSuggestions', () => {
const locked = new Set(input().locked);
const ruleKeys = new Set(['dated', 'faq']);
- it('keeps a replace whose words are in its passage, with the rules sent', () => {
- expect(keepSuggestions([suggestion()], passages, locked, ruleKeys)).toEqual([
+ it('keeps a replace whose words are in its passage, with the rules sent and its sources', () => {
+ // A source number the model wrote into its reason ("(S2)") isn't shown on the card.
+ const cited = suggestion({ reason: 'add a dated data point (rule) (S2)' });
+ expect(keepSuggestions([cited], passages, locked, ruleKeys, null, sourcing)).toEqual([
{
kind: 'replace',
block_text: 'Use good coffee and hot water.',
before_text: 'good coffee and hot water',
- after_text: '15 g of coffee and 250 g of water at 94 °C ([source, year])',
+ after_text: 'a 1:16 ratio of freshly ground coffee to hot water ([source, year])',
reason: 'add a dated data point (rule)',
rule_keys: ['dated'],
+ sources: [
+ {
+ kind: 'cited_page',
+ ref: 'https://sca.example/brew',
+ label: 'https://sca.example/brew',
+ },
+ { kind: 'fanout', ref: 'pour over ratio 1:16', label: 'Pour over ratio 1:16' },
+ ],
+ // 16 is marked to the fan-out whose words have it, unasked.
+ source_marks: [
+ { start: 4, end: 6, source: 1 },
+ { start: 16, end: 37, source: 0 },
+ ],
},
]);
});
+ it('keeps no number without a source (CE-033)', () => {
+ // A figure in none of the data: not kept, even marked to a source.
+ const invented = { after: '87% of baristas use freshly ground coffee' };
+ expect(
+ keepSuggestions([suggestion(invented)], passages, locked, ruleKeys, null, sourcing),
+ ).toEqual([]);
+ expect(
+ keepSuggestions(
+ [suggestion({ ...invented, marks: [{ words: '87% of baristas', source: 'S2' }] })],
+ passages,
+ locked,
+ ruleKeys,
+ null,
+ sourcing,
+ ),
+ ).toEqual([]);
+ // One the rules ask for (the keywords rule's "2026") needs no source.
+ const [asked] = keepSuggestions(
+ [suggestion({ after: 'the best pour-over gear for 2026', marks: [] })],
+ passages,
+ locked,
+ ruleKeys,
+ null,
+ { ...sourcing, known: knownNumbers('aim: best pour-over gear 2026') },
+ );
+ expect(asked).toMatchObject({ after_text: 'the best pour-over gear for 2026' });
+ // A source number written into the words is taken out.
+ const [plain] = keepSuggestions(
+ [suggestion({ after: 'freshly ground coffee (S2) and hot water', marks: [] })],
+ passages,
+ locked,
+ ruleKeys,
+ null,
+ sourcing,
+ );
+ expect(plain.after_text).toBe('freshly ground coffee and hot water');
+ // A number the page has already, or a count, needs none.
+ const [kept] = keepSuggestions(
+ [
+ suggestion({
+ passage: 2,
+ before: 'tastes better',
+ after: 'tastes better, in 3 ways',
+ sources: [],
+ marks: [],
+ }),
+ ],
+ draftPassages('<h1>Pour-over in 2026</h1><p>Pour-over coffee tastes better.</p>'),
+ new Set(),
+ ruleKeys,
+ );
+ expect(kept).toMatchObject({ after_text: 'tastes better, in 3 ways' });
+ expect(kept).not.toHaveProperty('sources');
+ expect(kept).not.toHaveProperty('source_marks');
+ });
+
it('drops one on a locked passage, words not in the passage, or no passage', () => {
expect(
keepSuggestions(
@@ -231,9 +319,9 @@ describe('keepSuggestions', () => {
});
it('keeps each change once', () => {
- expect(keepSuggestions([suggestion(), suggestion()], passages, locked, ruleKeys)).toHaveLength(
- 1,
- );
+ expect(
+ keepSuggestions([suggestion(), suggestion()], passages, locked, ruleKeys, null, sourcing),
+ ).toHaveLength(1);
});
});
@@ -503,24 +591,29 @@ describe('links to the pages and sources given', () => {
passage: 3,
before: '',
after:
- '<h3><a href="https://research.example/study">Study</a></h3><p>A <a href="https://research.example/study" target="_blank" onclick="x()">2025 study</a> found it.</p>',
+ '<h3><a href="https://research.example/study">Study</a></h3><p>A <a href="https://research.example/study" target="_blank" onclick="x()">recent study</a> found it.</p>',
rules: ['citeInline'],
+ sources: ['S1'],
+ marks: [{ words: 'recent study', source: 'S1' }],
}),
],
page,
new Set(),
new Set(['citeInline']),
links,
+ { numbered: numberSources({ pages: [{ url: 'https://research.example/study' }] }) },
);
expect(kept.after_text).toBe(
- '<h3>Study</h3><p>A <a href="https://research.example/study">2025 study</a> found it.</p>',
+ '<h3>Study</h3><p>A <a href="https://research.example/study">recent study</a> found it.</p>',
);
+ // Its mark is by the insert's text: "Study" then the paragraph.
+ expect(kept.source_marks).toEqual([{ start: 7, end: 19, source: 0 }]);
});
it('keeps at most 20 links on a replace, as the table allows', () => {
const many = Array.from(
{ length: 22 },
- (_, i) => `<a href="https://acme.example/pricing">plan ${i}</a>`,
+ (_, i) => `<a href="https://acme.example/pricing">plan ${String.fromCharCode(97 + i)}</a>`,
).join(' ');
const [kept] = keep({ after: `See ${many} for teams.` });
expect(kept.after_links).toHaveLength(20);
@@ -621,7 +714,11 @@ describe('fixDraftRules', () => {
usage: { inputTokens: 900, outputTokens: 200 },
});
- const result = await fixDraftRules({ draftId: DRAFT, brandId: BRAND, input: input() });
+ const result = await fixDraftRules({
+ draftId: DRAFT,
+ brandId: BRAND,
+ input: input({ sources: SOURCES }),
+ });
expect(reserveAiBudget).toHaveBeenCalledWith(
'org-1',
@@ -634,8 +731,15 @@ describe('fixDraftRules', () => {
system: expect.stringContaining(
'Never write an answer, a sentence or a FAQ into a heading',
),
+ // The data it writes from, numbered (CE-033).
+ prompt: expect.stringContaining(
+ 'S1 Fan-out (a search AI ran while answering): "Pour over ratio 1:16" (chatgpt)\nS2 Cited page (AI answers cite it today; answer better, never copy): https://sca.example/brew (publication)',
+ ),
}),
);
+ expect(generateObject.mock.calls[0][0].system).toContain(
+ "you don't see what a cited page says",
+ );
expect(result).toEqual({ count: 1, batchId: expect.any(String) });
const usage = writes.find((w) => w.table === 'prompt_improve_usage');
expect(usage.value).toMatchObject({
@@ -651,10 +755,31 @@ describe('fixDraftRules', () => {
action_id: 'act-1',
position: 0,
kind: 'replace',
+ sources: [
+ expect.objectContaining({ kind: 'cited_page', ref: 'https://sca.example/brew' }),
+ expect.objectContaining({ kind: 'fanout', ref: 'pour over ratio 1:16' }),
+ ],
+ source_marks: [
+ { start: 4, end: 6, source: 1 },
+ { start: 16, end: 37, source: 0 },
+ ],
}),
]);
});
+ it('numbers the brand’s prompts among those kept, first', async () => {
+ rows.prompts = [{ id: 'p1', text: 'What ratio for pour-over?' }];
+ generateObject.mockResolvedValue({ object: { suggestions: [] }, usage: {} });
+ await fixDraftRules({
+ draftId: DRAFT,
+ brandId: BRAND,
+ input: input({ sources: { ...SOURCES, promptIds: ['p1', 'p-other-brand'] } }),
+ });
+ expect(generateObject.mock.calls[0][0].prompt).toContain(
+ 'S1 Prompt (a question tracked in AI answers): "What ratio for pour-over?"\nS2 Fan-out',
+ );
+ });
+
it('keeps nothing when the agent found nothing it could change', async () => {
generateObject.mockResolvedValue({ object: { suggestions: [] }, usage: {} });
await expect(
diff --git a/server/src/lib/content-rewrite.js b/server/src/lib/content-rewrite.js
index ceafa0d03..f51e5e09e 100644
--- a/server/src/lib/content-rewrite.js
+++ b/server/src/lib/content-rewrite.js
@@ -3,6 +3,7 @@ import * as cheerio from 'cheerio';
import { z } from 'zod';
import { HEADING_LIMITS, passageKey } from './content-agent.js';
import { linkKey } from './content-links.js';
+import { sourcesField } from './content-sources.js';
/**
* Rewrite the page to these rules (Content Editor): the Content Agent
@@ -49,13 +50,15 @@ const INLINE_TAGS = new Set(['strong', 'em', 'b', 'i', 'br', 'a']);
export const rewriteSchema = z.object({
html: z.string().describe('The whole page rewritten, as HTML.'),
reason: z.string().describe('One short sentence on what changed.'),
+ sources: sourcesField,
});
export const REWRITE_SYSTEM_PROMPT = `You are the Content Agent for Answer Engine Optimization (AEO). You rewrite one existing web page, whole, so it meets the rules listed and AI assistants (ChatGPT, Perplexity, Gemini, Copilot, Google's AI Overviews) understand it, trust it and cite it. A person compares your page with theirs and accepts or rejects it.
How to rewrite:
- Meet every rule listed, and the writer's own rules. Aim at the Length given: the page's whole text, kept blocks included, within 20% of it. When the page is too long, cut repetition, filler and the least useful parts first, and keep its answers, facts and data.
-- Keep the page's facts and voice. Use only facts from the page, the brand and the brief. Never invent numbers, prices, dates, names, customers, sources or quotes; when the page needs a fact you don't have, write a placeholder in square brackets, e.g. [figure, source, year].
+- Keep the page's facts and voice. Use only facts from the page, the brand, the brief and your data. Never invent numbers, prices, dates, names, customers, sources or quotes; when the page needs a fact you don't have, write a placeholder in square brackets, e.g. [figure, source, year]. A number that isn't in them becomes a placeholder.
+- Put the numbers (S1, S2…) of the data the page uses in "sources".
- One H1, the page's title, first. Sections are H2s; questions and sub-sections are H3s.
- Answer first: under each heading, a short paragraph that answers it, then the detail.
- Headings are one short line: an H1 up to ${HEADING_LIMITS.h1} characters, others up to ${HEADING_LIMITS.other}. Never put a sentence or an answer in a heading.
diff --git a/server/src/lib/content-sources.js b/server/src/lib/content-sources.js
new file mode 100644
index 000000000..3ea858b20
--- /dev/null
+++ b/server/src/lib/content-sources.js
@@ -0,0 +1,321 @@
+import * as cheerio from 'cheerio';
+import { z } from 'zod';
+
+/**
+ * The person's data the Content Agent writes from, and what it says it used
+ * (Content Editor v1.1 §3b, CE-033): the sources the Sources tab keeps —
+ * prompts, fan-outs, cited pages, Search Console queries — numbered for the
+ * model (S1, S2…). Each suggestion names the sources behind it and marks the
+ * words each one supports, so the editor shows "Based on" chips and ¹ ² marks.
+ *
+ * And no number without a source. The model reads a source by its words
+ * (a question, a search), never its content, so a mark alone proves
+ * nothing: a number the agent adds must be in the page, the brand's or the
+ * brief's words, the rules, this year, or a source's own words — and then it
+ * is marked to that source. A claim (a %, a ×, a scale, a currency) must be
+ * known with the same unit or sign: "crm for 50 users" never sources "50%".
+ * A cited page's address is no words of its own. A suggestion with any
+ * other number is not kept; a page the agent writes whole gets a
+ * placeholder in its place.
+ */
+
+/** The most sources one suggestion names (content_draft_suggestions.sources, 00248). */
+export const MAX_SUGGESTION_SOURCES = 8;
+/** The most marks one suggestion keeps (source_marks, 00248). */
+export const MAX_SOURCE_MARKS = 12;
+/** What stands where a number had no source. */
+export const NUMBER_PLACEHOLDER = '[figure, source]';
+
+/** What a suggestion says it used, and the words each source supports. */
+export const sourcesField = z
+ .array(z.string())
+ .describe('The numbers (S1, S2…) of your data this change uses; [] when it uses none.');
+export const marksField = z
+ .array(
+ z.object({
+ words: z.string().describe('The words in "after" the source supports, copied exactly.'),
+ source: z.string().describe('Its number, e.g. S2.'),
+ }),
+ )
+ .describe('Each fact the change takes from your data, with its source.');
+
+/** The rule every prompt that uses the list gives the model. */
+export const SOURCES_RULE = `- Your data is numbered (S1, S2…) and listed by its words only: you don't see what a cited page says. Put the numbers of the ones a change uses in "sources", and mark the exact words each supports in "marks"; never write "S1" in the page's words. Add a number only when the page, the brand, the rules or your data's own words have it; otherwise write a placeholder in square brackets.`;
+
+/** A query as the Sources tab keys it: trimmed, spaces collapsed, lowercased (sources.ts normalizeQuery). */
+export function normalizeQuery(query) {
+ return String(query ?? '')
+ .trim()
+ .replace(/\s+/g, ' ')
+ .toLowerCase();
+}
+
+/**
+ * The sources numbered: [{ id: 'S1', kind, ref, label, detail }], refs as the
+ * Sources tab keys its rows (a prompt's id, a normalized query, a page's
+ * address), so the editor finds each one there.
+ */
+export function numberSources({ prompts = [], fanouts = [], pages = [], queries = [] }) {
+ const list = [
+ ...prompts.map((p) => ({ kind: 'prompt', ref: p.id, label: p.text })),
+ ...fanouts.map((f) => ({
+ kind: 'fanout',
+ ref: normalizeQuery(f.query),
+ label: f.query,
+ detail: f.platforms?.length ? f.platforms.join(', ') : '',
+ })),
+ ...pages.map((p) => ({ kind: 'cited_page', ref: p.url, label: p.url, detail: p.kind })),
+ ...queries.map((q) => ({ kind: 'gsc_query', ref: normalizeQuery(q), label: q })),
+ ].filter((s) => s.ref && s.label);
+ return list.map((s, i) => ({ id: `S${i + 1}`, ...s }));
+}
+
+const KIND_NAMES = {
+ prompt: 'Prompt (a question tracked in AI answers)',
+ fanout: 'Fan-out (a search AI ran while answering)',
+ cited_page: 'Cited page (AI answers cite it today; answer better, never copy)',
+ gsc_query: 'Search Console query (a Google search people use)',
+};
+
+/** The numbered list as the model reads it, or '' with none. */
+export function sourcesPrompt(numbered) {
+ if (!numbered.length) return '';
+ const lines = numbered.map(
+ (s) =>
+ `${s.id} ${KIND_NAMES[s.kind]}: ${s.kind === 'cited_page' ? s.label : `"${s.label}"`}${s.detail ? ` (${s.detail})` : ''}`,
+ );
+ return `Your data, numbered (cite by number):\n${lines.join('\n')}`;
+}
+
+/** A source number written into the words in brackets ("(S2)", "[S1, S3]"): never the page's. */
+const SOURCE_ID = /\s?[([]S\d{1,3}(?:\s*[,;]\s*S\d{1,3})*[)\]]/g;
+
+/** Words with the source numbers the model wrote into them taken out. */
+export function stripSourceIds(text) {
+ return String(text ?? '').replace(SOURCE_ID, '');
+}
+
+/**
+ * A number as the guard reads it: digits with their separators, not stuck to
+ * a letter before them ("B2B", "H2", "Web3" are words).
+ */
+const NUMBER = /(?<!\p{L})\d+(?:[.,]\d+)*/gu;
+const CURRENCY = /[$€£¥₺]/;
+/** What makes a lone digit a claim: a percent, a times, a scale. */
+const UNIT_AFTER =
+ /^\s?(?:%|×|[xX]\b|[kKMB]\b|bn\b|mn\b|[Mm]illions?\b|[Bb]illions?\b|[Tt]housands?\b|[Tt]rillions?\b)/;
+
+/** A claim's unit, one name for each way it is written: "40%", "3x", "2M", "$40". */
+function unitOf(text, start, end) {
+ const before = text[start - 1] ?? '';
+ if (CURRENCY.test(before)) return before;
+ const unit = text.slice(end).match(UNIT_AFTER)?.[0].trim().toLowerCase();
+ if (!unit) return '';
+ if (unit === '%') return '%';
+ if (unit === '×' || unit === 'x') return '×';
+ if (unit === 'k' || unit.startsWith('thousand')) return 'thousand';
+ if (unit === 'm' || unit === 'mn' || unit.startsWith('million')) return 'million';
+ if (unit === 'b' || unit === 'bn' || unit.startsWith('billion')) return 'billion';
+ return 'trillion';
+}
+/** A placeholder the agent leaves ("[figure, source, 2025]"): it holds no claim. */
+const BRACKETS = /\[[^\]]*\]/g;
+
+/** A number's value as compared: thousands separators dropped ("1,299" is 1299). */
+const valueOf = (token) => token.replace(/[.,](?=\d{3}(?!\d))/g, '');
+
+/** The numbers a text holds, each with where it is and its unit ('' for none). */
+export function numbersIn(text) {
+ const s = String(text ?? '');
+ const found = [];
+ for (const m of s.matchAll(NUMBER)) {
+ const end = m.index + m[0].length;
+ found.push({ value: valueOf(m[0]), unit: unitOf(s, m.index, end), start: m.index, end });
+ }
+ return found;
+}
+
+/** A number as a known set holds it: its value, and with a unit its value and unit. */
+const unitKey = (n) => `${n.value}|${n.unit}`;
+
+/**
+ * Every number in these texts: each value, so a plain number matches it
+ * written any way, and each value with its unit, which a claim must match.
+ */
+export function knownNumbers(...texts) {
+ return new Set(
+ texts.flatMap((text) =>
+ numbersIn(text).flatMap((n) => (n.unit ? [n.value, unitKey(n)] : [n.value])),
+ ),
+ );
+}
+
+/** Today as the agent may write it: its year alone ("23" on the 23rd would let "23%" through). */
+export function todayText(now = new Date()) {
+ return `${now.getUTCFullYear()}`;
+}
+
+/** A source's words its numbers are read from: a cited page's address is none ("/2024/03/15/post-1234"). */
+export function sourceWords(source) {
+ return source.kind === 'cited_page' ? '' : `${source.label} ${source.detail ?? ''}`;
+}
+
+/** Tags whose text is never a page's words. */
+const NOT_WORDS = new Set(['script', 'style', 'noscript', 'template', 'svg', 'textarea']);
+
+/** All of a page's words, tables and HTML blocks too, each piece apart: where its numbers are read. */
+export function htmlText(html) {
+ const $ = cheerio.load(html || '', null, false);
+ const pieces = [];
+ const walk = (nodes) => {
+ for (const node of nodes) {
+ if (node.type === 'text') pieces.push(node.data);
+ else if (node.type === 'tag' && !NOT_WORDS.has(node.name)) walk(node.children ?? []);
+ }
+ };
+ walk($.root().contents().get());
+ return pieces.join(' ');
+}
+
+/**
+ * HTML's text nodes, each with where it starts in the HTML read as text (as
+ * cheerio's .text() and a browser's textContent join them, with nothing
+ * between blocks): numbers are read node by node, so "Option 1" and "2
+ * seats" in two items never read as 12.
+ */
+export function textPieces(html) {
+ const $ = cheerio.load(html || '', null, false);
+ const pieces = [];
+ let at = 0;
+ const walk = (nodes) => {
+ for (const node of nodes) {
+ if (node.type === 'text') {
+ pieces.push({ text: node.data, start: at });
+ at += node.data.length;
+ } else if (node.type === 'tag') walk(node.children ?? []);
+ }
+ };
+ walk($.root().contents().get());
+ return pieces;
+}
+
+/**
+ * The numbers a text adds: not known, outside a placeholder, and not a lone
+ * digit used as a count ("3 ways", "Step 2") — one with a %, a ×, a scale
+ * or a currency sign is a claim and counts.
+ */
+export function addedNumbers(text, known) {
+ const s = String(text ?? '').replace(BRACKETS, (m) => ' '.repeat(m.length));
+ return numbersIn(s).filter((n) => {
+ // A claim is known only with its unit or sign; a plain number as any.
+ if (known.has(n.unit ? unitKey(n) : n.value)) return false;
+ return n.unit !== '' || n.value.length > 1;
+ });
+}
+
+/**
+ * A suggestion's sources and marks, as kept — or null when it adds a number
+ * none of them has. `pieces` are its words (one piece for a replace's, an
+ * insert's text nodes); `known` the numbers it may write unmarked (the
+ * page's, the brand's, the brief's, the rules', today's).
+ *
+ * Sources: the ones its marks name, then the ones it names, each once and
+ * at most MAX_SUGGESTION_SOURCES, as [{ kind, ref, label }]. Marks: each
+ * mark's words found in the text, { start, end, source } (an index into the
+ * sources), in order and apart; then a mark on each number it adds from a
+ * source's own words, to that source. Ids the list doesn't have are dropped.
+ */
+export function sourceSuggestion({ named, marks, pieces, numbered, known }) {
+ const text = pieces.map((p) => p.text).join('');
+ const byId = new Map(numbered.map((s) => [s.id.toUpperCase(), s]));
+ const sources = [];
+ const indexOf = (source) => {
+ if (!source) return -1;
+ let i = sources.findIndex((s) => s.kind === source.kind && s.ref === source.ref);
+ if (i === -1 && sources.length < MAX_SUGGESTION_SOURCES) {
+ sources.push({ kind: source.kind, ref: source.ref, label: source.label });
+ i = sources.length - 1;
+ }
+ return i;
+ };
+ const sourceOf = (id) =>
+ byId.get(
+ String(id ?? '')
+ .trim()
+ .toUpperCase(),
+ );
+ // A marked source first: the cap never drops one a mark needs.
+ for (const mark of marks ?? []) indexOf(sourceOf(mark.source));
+ for (const id of named ?? []) indexOf(sourceOf(id));
+
+ const kept = [];
+ const free = (start, end) => kept.every((k) => end <= k.start || start >= k.end);
+ for (const mark of marks ?? []) {
+ if (kept.length >= MAX_SOURCE_MARKS) break;
+ // The words as text: tags and entities a model copies in don't count.
+ const words = cheerio
+ .load(String(mark.words ?? ''), null, false)
+ .root()
+ .text()
+ .trim();
+ const source = indexOf(sourceOf(mark.source));
+ if (!words || source === -1) continue;
+ let at = text.indexOf(words);
+ while (at !== -1 && !free(at, at + words.length)) at = text.indexOf(words, at + 1);
+ if (at !== -1) kept.push({ start: at, end: at + words.length, source });
+ }
+
+ // Each number it adds: the page's own, or one of its sources' words'.
+ const own = numbered.map((s) => knownNumbers(sourceWords(s)));
+ for (const piece of pieces) {
+ for (const n of addedNumbers(piece.text, known)) {
+ const start = piece.start + n.start;
+ const end = piece.start + n.end;
+ const from = numbered.findIndex((_, i) => own[i].has(n.unit ? unitKey(n) : n.value));
+ if (from === -1) return null;
+ const source = indexOf(numbered[from]);
+ if (source === -1) return null;
+ const marked = kept.some(
+ (k) => k.start <= start && end <= k.end && sources[k.source].ref === numbered[from].ref,
+ );
+ if (!marked && free(start, end) && kept.length < MAX_SOURCE_MARKS) {
+ kept.push({ start, end, source });
+ }
+ }
+ }
+ kept.sort((a, b) => a.start - b.start);
+ return { sources, marks: kept };
+}
+
+/** A text with each number it adds put as a placeholder: for a page written whole, with no marks. */
+export function placeholderNumbers(text, known) {
+ const added = addedNumbers(text, known);
+ let out = String(text ?? '');
+ for (const n of added.reverse()) {
+ // The sign and unit go with it: "$40" and "40%" become the placeholder.
+ let start = n.start;
+ let end = n.end;
+ if (CURRENCY.test(out[start - 1] ?? '')) start -= 1;
+ const unit = out.slice(end).match(UNIT_AFTER);
+ if (unit) end += unit[0].length;
+ out = `${out.slice(0, start)}${NUMBER_PLACEHOLDER}${out.slice(end)}`;
+ }
+ return out;
+}
+
+/** Tags whose text a page's placeholders never touch: code and what isn't words. */
+const KEPT_AS_IS = new Set([...NOT_WORDS, 'code', 'pre']);
+
+/** An HTML page with each number it adds put as a placeholder, in its words only. */
+export function placeholderNumbersInHtml(html, known) {
+ const $ = cheerio.load(html || '', null, false);
+ const walk = (nodes) => {
+ for (const node of nodes) {
+ if (node.type === 'text') node.data = placeholderNumbers(stripSourceIds(node.data), known);
+ // Attributes are left alone.
+ else if (node.type === 'tag' && !KEPT_AS_IS.has(node.name)) walk(node.children ?? []);
+ }
+ };
+ walk($.root().contents().get());
+ return $.html();
+}
diff --git a/server/src/lib/content-sources.test.js b/server/src/lib/content-sources.test.js
new file mode 100644
index 000000000..0f556513f
--- /dev/null
+++ b/server/src/lib/content-sources.test.js
@@ -0,0 +1,259 @@
+import { describe, expect, it } from 'vitest';
+import {
+ MAX_SOURCE_MARKS,
+ MAX_SUGGESTION_SOURCES,
+ NUMBER_PLACEHOLDER,
+ addedNumbers,
+ htmlText,
+ knownNumbers,
+ normalizeQuery,
+ numberSources,
+ placeholderNumbers,
+ placeholderNumbersInHtml,
+ sourceSuggestion,
+ sourcesPrompt,
+ stripSourceIds,
+ textPieces,
+ todayText,
+} from './content-sources.js';
+
+/**
+ * The data the Content Agent writes from (Content Editor v1.1, CE-033):
+ * numbered for the model, named and marked on each suggestion, and no number
+ * without a source.
+ */
+
+const numbered = numberSources({
+ prompts: [{ id: 'p1', text: 'Best LLM visibility tracker?' }],
+ fanouts: [{ query: ' Best LLM Visibility Tracker 2026 ', platforms: ['chatgpt'] }],
+ pages: [{ url: 'https://profound.com/blog/ai-visibility', kind: 'competitor' }],
+ queries: ['llm visibility tool'],
+});
+
+describe('numberSources', () => {
+ it('numbers prompts, fan-outs, cited pages and queries, keyed as the Sources tab keys them', () => {
+ expect(numbered).toEqual([
+ { id: 'S1', kind: 'prompt', ref: 'p1', label: 'Best LLM visibility tracker?' },
+ {
+ id: 'S2',
+ kind: 'fanout',
+ ref: 'best llm visibility tracker 2026',
+ label: ' Best LLM Visibility Tracker 2026 ',
+ detail: 'chatgpt',
+ },
+ {
+ id: 'S3',
+ kind: 'cited_page',
+ ref: 'https://profound.com/blog/ai-visibility',
+ label: 'https://profound.com/blog/ai-visibility',
+ detail: 'competitor',
+ },
+ { id: 'S4', kind: 'gsc_query', ref: 'llm visibility tool', label: 'llm visibility tool' },
+ ]);
+ expect(normalizeQuery(' A b ')).toBe('a b');
+ });
+
+ it('lists them for the model by number, or nothing with none', () => {
+ const prompt = sourcesPrompt(numbered);
+ expect(prompt).toMatch(/^Your data, numbered \(cite by number\):\n/);
+ expect(prompt).toContain(
+ 'S3 Cited page (AI answers cite it today; answer better, never copy): https://profound.com/blog/ai-visibility (competitor)',
+ );
+ expect(prompt).toContain(
+ 'S4 Search Console query (a Google search people use): "llm visibility tool"',
+ );
+ expect(sourcesPrompt([])).toBe('');
+ });
+});
+
+describe('sourceSuggestion', () => {
+ const known = knownNumbers('Trackers compared in 2026.');
+ const one = (text) => [{ text, start: 0 }];
+
+ it('keeps the sources named and each mark where its words are, marked ones first', () => {
+ const text = 'Trackers cover AI answers, per Profound, for the llm visibility tool.';
+ expect(
+ sourceSuggestion({
+ named: ['S2', 's2', 'S3'],
+ marks: [
+ { words: 'per Profound', source: 'S3' },
+ { words: '<b>llm visibility tool</b>', source: 'S4' },
+ ],
+ pieces: one(text),
+ numbered,
+ known,
+ }),
+ ).toEqual({
+ sources: [
+ {
+ kind: 'cited_page',
+ ref: 'https://profound.com/blog/ai-visibility',
+ label: 'https://profound.com/blog/ai-visibility',
+ },
+ { kind: 'gsc_query', ref: 'llm visibility tool', label: 'llm visibility tool' },
+ {
+ kind: 'fanout',
+ ref: 'best llm visibility tracker 2026',
+ label: ' Best LLM Visibility Tracker 2026 ',
+ },
+ ],
+ marks: [
+ { start: 27, end: 39, source: 0 },
+ { start: 49, end: 68, source: 1 },
+ ],
+ });
+ });
+
+ it('drops ids it doesn’t have, words not in the text and overlaps', () => {
+ const text = 'Trackers cover AI answers, per Profound.';
+ expect(
+ sourceSuggestion({
+ named: ['S9'],
+ marks: [
+ { words: 'nowhere', source: 'S3' },
+ { words: 'AI answers', source: 'S9' },
+ { words: 'AI answers, per Profound', source: 'S3' },
+ { words: 'per Profound', source: 'S2' },
+ ],
+ pieces: one(text),
+ numbered,
+ known,
+ }).marks,
+ ).toEqual([{ start: 15, end: 39, source: 0 }]);
+ });
+
+ it('keeps no number but the page’s, today’s or a source’s own words’, marked to it', () => {
+ // 2026 is the page's; 87% is no one's: not kept, marked or not.
+ expect(
+ sourceSuggestion({
+ named: ['S3'],
+ marks: [{ words: '87% of buyers', source: 'S3' }],
+ pieces: one('In 2026, 87% of buyers ask AI.'),
+ numbered,
+ known,
+ }),
+ ).toBeNull();
+ // A number in a fan-out's own words is marked to it, unasked.
+ const fanout = numberSources({ fanouts: [{ query: 'pour over ratio 1:16' }] });
+ expect(
+ sourceSuggestion({
+ named: [],
+ marks: [],
+ pieces: one('Use a 1:16 ratio.'),
+ numbered: fanout,
+ known: new Set(),
+ }),
+ ).toEqual({
+ sources: [{ kind: 'fanout', ref: 'pour over ratio 1:16', label: 'pour over ratio 1:16' }],
+ marks: [{ start: 8, end: 10, source: 0 }],
+ });
+ });
+
+ it('sources a claim only from a number with its unit, and never from a cited page’s address', () => {
+ // "crm for 50 users" has 50 users, not 50%.
+ const fanout = numberSources({ fanouts: [{ query: 'crm for 50 users' }] });
+ const suggest = (text, numbered) =>
+ sourceSuggestion({ named: [], marks: [], pieces: one(text), numbered, known: new Set() });
+ expect(suggest('50% of teams use one.', fanout)).toBeNull();
+ expect(suggest('Plans for 50 users.', fanout)).toMatchObject({
+ marks: [{ start: 10, end: 12, source: 0 }],
+ });
+ // A dated address is no words of the page's.
+ const page = numberSources({
+ pages: [{ url: 'https://blog.example/2024/03/15/post-1234', kind: 'blog' }],
+ });
+ expect(suggest('Over 1234 teams switched in 2024.', page)).toBeNull();
+ });
+
+ it('reads an insert node by node: numbers in two items never run together', () => {
+ const pieces = textPieces('<ul><li>Option 1</li><li>2 seats</li></ul>');
+ expect(pieces).toEqual([
+ { text: 'Option 1', start: 0 },
+ { text: '2 seats', start: 8 },
+ ]);
+ expect(
+ sourceSuggestion({ named: [], marks: [], pieces, numbered: [], known: new Set() }),
+ ).toEqual({ sources: [], marks: [] });
+ });
+
+ it('keeps at most so many sources and marks', () => {
+ const many = numberSources({
+ fanouts: Array.from({ length: 20 }, (_, i) => ({ query: `q${String.fromCharCode(97 + i)}` })),
+ });
+ const long = many.map((s) => `${s.label} `.repeat(2)).join('');
+ const result = sourceSuggestion({
+ named: many.map((s) => s.id),
+ marks: many.flatMap((s) => [
+ { words: s.label, source: s.id },
+ { words: s.label, source: s.id },
+ ]),
+ pieces: one(long),
+ numbered: many,
+ known: new Set(),
+ });
+ expect(result.sources).toHaveLength(MAX_SUGGESTION_SOURCES);
+ expect(result.marks).toHaveLength(MAX_SOURCE_MARKS);
+ });
+});
+
+describe('no number without a source', () => {
+ const known = knownNumbers('Trackers in 2026 cost $1,299 a year.', 'llm visibility tool');
+
+ it('finds the numbers a text adds, not those known, in a placeholder, or a lone count', () => {
+ expect(
+ addedNumbers(
+ 'In 2026, 3 tools cost 1299 dollars; 40% more, 2× faster, $9 plans, 5 million users [figure, 2025].',
+ known,
+ ).map((n) => n.value),
+ ).toEqual(['40', '2', '9', '5']);
+ });
+
+ it('knows this year, not today’s day or month, and takes the source numbers out of the words', () => {
+ const today = new Date('2026-10-23T12:00:00Z');
+ expect(todayText(today)).toBe('2026');
+ // On Oct 23, "23%" is no fact of the date's.
+ expect(
+ addedNumbers('23% of buyers in 2026, 10x faster', knownNumbers(todayText(today))).map(
+ (n) => n.value,
+ ),
+ ).toEqual(['23', '10']);
+ expect(stripSourceIds('Trackers (S2) cover AI [S1, S3]. Amazon S3 stays.')).toBe(
+ 'Trackers cover AI. Amazon S3 stays.',
+ );
+ });
+
+ it('reads no figure in words with digits, and matches a claim to its unit', () => {
+ expect(addedNumbers('B2B software for H2 teams on Web3', new Set())).toEqual([]);
+ expect(placeholderNumbers('B2B software, 2B users', new Set())).toBe(
+ `B2B software, ${NUMBER_PLACEHOLDER} users`,
+ );
+ const units = knownNumbers('Save 40% and $49 a month, 3x faster, 2M users');
+ expect(addedNumbers('40% off, $49, 3× faster, 2 million users', units)).toEqual([]);
+ expect(addedNumbers('$40, 49%, 3 million', units).map((n) => n.value)).toEqual([
+ '40',
+ '49',
+ '3',
+ ]);
+ });
+
+ it('puts a placeholder where a page written whole adds one, sign and unit with it', () => {
+ expect(placeholderNumbers('Teams see 40% more, at $49 a month, in 2026.', known)).toBe(
+ `Teams see ${NUMBER_PLACEHOLDER} more, at ${NUMBER_PLACEHOLDER} a month, in 2026.`,
+ );
+ expect(
+ placeholderNumbersInHtml(
+ '<h1>Guide 2026</h1><p>Up <b>35%</b> in <a href="/r/77">77 days</a>.</p><pre>port 8080</pre>',
+ known,
+ ),
+ ).toBe(
+ `<h1>Guide 2026</h1><p>Up <b>${NUMBER_PLACEHOLDER}</b> in <a href="/r/77">${NUMBER_PLACEHOLDER} days</a>.</p><pre>port 8080</pre>`,
+ );
+ });
+
+ it('reads a page’s numbers from all its text, a table’s too, each cell apart', () => {
+ expect(htmlText('<p>Ratio</p><table><tr><td>1:16</td><td>2026</td></tr></table>')).toBe(
+ 'Ratio 1:16 2026',
+ );
+ expect([...knownNumbers(htmlText('<td>1:16</td><td>2026</td>'))]).toEqual(['1', '16', '2026']);
+ });
+});
diff --git a/server/src/lib/content-writer.js b/server/src/lib/content-writer.js
index 168022230..b81093945 100644
--- a/server/src/lib/content-writer.js
+++ b/server/src/lib/content-writer.js
@@ -13,12 +13,25 @@ import {
keepSuggestions,
passageKey,
promptPassages,
+ readPrompts,
suggestionsSchema,
WRITING_STALE_MS,
} from './content-agent.js';
import { contentBriefModelId, rebuildSources } from './content-brief.js';
import { linkAllowList, linkTargetsPrompt, readLinkTargets } from './content-links.js';
import { pageTypeFormat } from './content-page-types.js';
+import {
+ SOURCES_RULE,
+ htmlText,
+ knownNumbers,
+ numberSources,
+ placeholderNumbers,
+ placeholderNumbersInHtml,
+ sourceSuggestion,
+ sourceWords,
+ stripSourceIds,
+ todayText,
+} from './content-sources.js';
import {
MAX_PAGE_HTML,
MAX_REWRITE_CHARS,
@@ -114,7 +127,7 @@ How to write:
- Short paragraphs and plain sentences. Lists where a reader compares or follows steps.
- Follow every rule listed, and the writer's own rules.
- For each fan-out a rule names, use its words, not questions of your own: a section heading for fanoutH2, an FAQ question ending in "?" for fanoutFaq.
-- Use only facts from the brand and the brief. Never invent numbers, prices, dates, names, customers, sources or quotes. When the page needs a fact you don't have, write a placeholder in square brackets, e.g. [price], [figure, source, year].
+- Use only facts from the brand, the brief and your data. Never invent numbers, prices, dates, names, customers, sources or quotes. When the page needs a fact you don't have, write a placeholder in square brackets, e.g. [price], [figure, source, year]. A number that isn't in them becomes a placeholder.
- Plain text in every field: no HTML, no Markdown.
- Write in the language asked for.`;
@@ -129,7 +142,8 @@ ${LINK_RULE}
${FANOUT_RULE}
- Never change a passage marked LOCKED: AI assistants quote its wording today. You may insert after it.
- Put the keys of the rules a change meets in "rules" (none when it meets none).
-- Use only facts from the page and the brand. Never invent numbers, prices, dates, names, sources or quotes; write a placeholder in square brackets instead, e.g. [figure, source, year].
+- Use only facts from the page, the brand and your data. Never invent numbers, prices, dates, names, sources or quotes; write a placeholder in square brackets instead, e.g. [figure, source, year].
+${SOURCES_RULE}
- Keep the page's voice. The most useful changes first, at most ${MAX_AGENT_SUGGESTIONS}.
- "reason" says in a few words what the change does, e.g. "answer the search 'x' (fan-out)".
- Write in the language asked for.`;
@@ -166,6 +180,24 @@ export function renderPage(page) {
const list = (items) => (items.length ? items.map((item) => `- ${item}`).join('\n') : '- none');
+/** A written page with each number its sources don't have put as a placeholder (CE-033). */
+export function sourcedPage(page, known) {
+ const fix = (text) => placeholderNumbers(stripSourceIds(text), known);
+ return {
+ ...page,
+ title: fix(page.title),
+ intro: page.intro.map(fix),
+ sections: page.sections.map((section) => ({
+ ...section,
+ heading: fix(section.heading),
+ paragraphs: section.paragraphs.map(fix),
+ bullets: section.bullets.map(fix),
+ })),
+ faqHeading: fix(page.faqHeading),
+ faq: page.faq.map((item) => ({ question: fix(item.question), answer: fix(item.answer) })),
+ };
+}
+
/** The brief as the model reads it: the draft's own, else its opportunity's. */
export function briefText(draftBrief, opportunityBrief) {
if (draftBrief?.outline?.length || draftBrief?.goal) {
@@ -199,7 +231,7 @@ Call to action: ${opportunityBrief.callToAction || '—'}`;
export function buildWritePrompt({
brand,
draft,
- prompts,
+ numbered = [],
brief,
input,
passages,
@@ -209,6 +241,8 @@ export function buildWritePrompt({
current = null,
}) {
const { sources } = input;
+ // The data, numbered (S1, S2…) as the agent cites it (CE-033).
+ const of = (kind) => numbered.filter((s) => s.kind === kind);
const rules = input.rules.map((r) => `${r.key}: ${r.name}${r.detail ? ` — ${r.detail}` : ''}`);
const own = input.textRules.map((text) => `- ${text}`);
const page = current
@@ -233,17 +267,19 @@ Length: about ${sources.length} characters.
Brief:
${brief}
+Your data is numbered below (S1, S2…), by its words only. Name the ones you use where asked; never write these numbers in the page's words.
+
Questions the page must answer (tracked prompts):
-${list(prompts)}
+${list(of('prompt').map((s) => `${s.id} ${s.label}`))}
AI searches (fan-outs) run while answering them, the most searched first:
-${list(sources.fanouts.map((f) => `"${f.query}"`))}
+${list(of('fanout').map((s) => `${s.id} "${s.label}"`))}
Google searches people use (Search Console):
-${list(sources.queries)}
+${list(of('gsc_query').map((s) => `${s.id} "${s.label}"`))}
Pages AI cites for these questions today (answer better than them, never copy them):
-${list(sources.pages.map((p) => p.url))}
+${list(of('cited_page').map((s) => `${s.id} ${s.label}`))}
Rules (key: rule — what it asks):
${list(rules)}
@@ -440,7 +476,7 @@ async function letGo(draftId) {
* is put back as it was (content-rewrite.js); a rewrite that drops one, or
* leaves no page, fails the run. The draft's status doesn't change.
*/
-async function rewritePage({ draft, brand, model, input, budget, prompts, brief }) {
+async function rewritePage({ draft, brand, model, input, budget, numbered, known, brief }) {
const page = keepBlocks(draft.body_html, new Set(input.locked.map(passageKey)));
const ruleKeys = new Set(input.rules.map((r) => r.key));
// The Length rule's target; with Length off, the page keeps its length.
@@ -459,7 +495,7 @@ async function rewritePage({ draft, brand, model, input, budget, prompts, brief
prompt: buildWritePrompt({
brand,
draft,
- prompts,
+ numbered,
brief,
input: { ...input, sources: { ...input.sources, length } },
linkTargets: linkTargetsPrompt(targets, ruleKeys),
@@ -475,13 +511,16 @@ async function rewritePage({ draft, brand, model, input, budget, prompts, brief
rewriteLinks(draft.body_html, linkAllowList(targets)),
{ h1Kept: page.h1Token !== null, originalH1: page.h1 },
);
- const { html, missing } = restoreKept(cleaned, page.kept, {
+ const { html: restored, missing } = restoreKept(cleaned, page.kept, {
word: page.word,
h1Token: page.h1Token,
});
if (missing.length) {
throw new Error(`The rewrite left out ${missing.length} kept block(s)`);
}
+ // No number without a source: one the page, the brand, the brief or the
+ // data doesn't have becomes a placeholder (CE-033).
+ const html = placeholderNumbersInHtml(restored, known);
if (!textLength(html)) throw new Error('The agent left no page to review');
if (html.length > MAX_PAGE_HTML) throw new Error('The rewritten page is too long to keep');
// A batch that landed during the run stays the one to decide.
@@ -489,6 +528,14 @@ async function rewritePage({ draft, brand, model, input, budget, prompts, brief
logger.info({ draftId: draft.id }, '[content-writer] open suggestions came in during the run');
return await letGo(draft.id);
}
+ // The data it says it wrote from (CE-033).
+ const { sources } = sourceSuggestion({
+ named: object.sources,
+ marks: [],
+ pieces: [],
+ numbered,
+ known,
+ });
const batchId = randomUUID();
const { error: insertError } = await supabaseAdmin.from('content_draft_suggestions').insert({
draft_id: draft.id,
@@ -502,8 +549,9 @@ async function rewritePage({ draft, brand, model, input, budget, prompts, brief
before_text: '',
before_html: draft.body_html,
after_text: html,
- reason: clean(object.reason).slice(0, 300) || 'Rewrote the page to the rules',
+ reason: clean(stripSourceIds(object.reason)).slice(0, 300) || 'Rewrote the page to the rules',
rule_keys: [...ruleKeys],
+ ...(sources.length ? { sources } : {}),
});
if (insertError) throw insertError;
if (!(await finish(draft.id, { agent_state: null }, { openOnly: true }))) {
@@ -526,15 +574,8 @@ async function rewritePage({ draft, brand, model, input, budget, prompts, brief
*/
export async function runDraftWriting({ draft, brand, model, input, budget, rewrite = false }) {
try {
- const [promptsRes, opportunityRes] = await Promise.all([
- input.sources.promptIds.length
- ? supabaseAdmin
- // Through the prompt's set, not its topic: a prompt may have no topic.
- .from('prompts')
- .select('id, text, prompt_sets!inner(brand_id)')
- .in('id', input.sources.promptIds)
- .eq('prompt_sets.brand_id', draft.brand_id)
- : Promise.resolve({ data: [], error: null }),
+ const [prompts, opportunityRes] = await Promise.all([
+ readPrompts(draft.brand_id, input.sources.promptIds),
draft.opportunity_id && !draft.brief
? supabaseAdmin
.from('content_opportunities')
@@ -544,13 +585,41 @@ export async function runDraftWriting({ draft, brand, model, input, budget, rewr
.maybeSingle()
: Promise.resolve({ data: null, error: null }),
]);
- if (promptsRes.error) throw promptsRes.error;
if (opportunityRes.error) throw opportunityRes.error;
- const prompts = (promptsRes.data ?? []).map((p) => p.text);
const brief = briefText(draft.brief, opportunityRes.data?.brief);
+ // The data it writes from, numbered (CE-033); the numbers a suggestion
+ // may write unmarked (the page's, the brand's, the brief's, the rules',
+ // today's), and those a page written whole may (the sources' words too).
+ const numbered = numberSources({
+ prompts,
+ fanouts: input.sources.fanouts,
+ pages: input.sources.pages,
+ queries: input.sources.queries,
+ });
+ const known = knownNumbers(
+ htmlText(draft.body_html),
+ draft.title,
+ brand.name,
+ brand.industry,
+ brand.description,
+ brief,
+ ...input.rules.flatMap((r) => [r.name, r.detail]),
+ ...input.textRules,
+ todayText(),
+ );
+ const knownInPage = new Set([...known, ...knownNumbers(...numbered.map(sourceWords))]);
if (rewrite) {
- return await rewritePage({ draft, brand, model, input, budget, prompts, brief });
+ return await rewritePage({
+ draft,
+ brand,
+ model,
+ input,
+ budget,
+ numbered,
+ known: knownInPage,
+ brief,
+ });
}
if (draft.method === 'create') {
@@ -558,11 +627,13 @@ export async function runDraftWriting({ draft, brand, model, input, budget, rewr
model,
schema: pageSchema,
system: WRITE_SYSTEM_PROMPT,
- prompt: buildWritePrompt({ brand, draft, prompts, brief, input }),
+ prompt: buildWritePrompt({ brand, draft, numbered, brief, input }),
abortSignal: AbortSignal.timeout(CALL_TIMEOUT_MS),
});
await budget.charge(usage);
- const title = clean(object.title).slice(0, 300) || draft.title;
+ // No number without a source: a placeholder where one had none.
+ const written = sourcedPage(object, knownInPage);
+ const title = clean(written.title).slice(0, 300) || draft.title;
// Try again over a page the person has written in: History keeps it
// first. Their saves wait while the agent writes (saveContentDraft).
if (draftPassages(draft.body_html).some((p) => p.tag !== 'h1')) {
@@ -572,11 +643,11 @@ export async function runDraftWriting({ draft, brand, model, input, budget, rewr
});
if (keepError) throw keepError;
}
- const written = await finish(
+ const saved = await finish(
draft.id,
{
title,
- body_html: renderPage({ ...object, title }),
+ body_html: renderPage({ ...written, title }),
status: 'in_review',
author: 'agent',
agent_state: null,
@@ -584,7 +655,7 @@ export async function runDraftWriting({ draft, brand, model, input, budget, rewr
{ openOnly: true },
);
// Awaited here, so a failure to let go is caught below.
- return written ? { written: true } : await letGo(draft.id);
+ return saved ? { written: true } : await letGo(draft.id);
}
const { passages, more } = promptPassages(draftPassages(draft.body_html));
@@ -605,7 +676,7 @@ export async function runDraftWriting({ draft, brand, model, input, budget, rewr
prompt: buildWritePrompt({
brand,
draft,
- prompts,
+ numbered,
brief,
input,
passages,
@@ -622,6 +693,7 @@ export async function runDraftWriting({ draft, brand, model, input, budget, rewr
lockedKeys,
ruleKeys,
linkAllowList(targets),
+ { numbered, known },
);
if (!rows.length) throw new Error('The agent left no suggestion it could place');
// A batch that landed during the run (Fix open rules, the API) stays the
diff --git a/server/src/lib/content-writer.test.js b/server/src/lib/content-writer.test.js
index b75fcc92a..9892e6a38 100644
--- a/server/src/lib/content-writer.test.js
+++ b/server/src/lib/content-writer.test.js
@@ -218,8 +218,9 @@ describe('startDraftWriting', () => {
author: 'agent',
agent_state: null,
});
+ // No number without a source (CE-033): none of the data has 15 or 250.
expect(draftUpdates()[1].body_html).toMatch(
- /^<h1>How to brew pour-over coffee<\/h1><p>Use 15 g/,
+ /^<h1>How to brew pour-over coffee<\/h1><p>Use \[figure, source\] g of coffee for \[figure, source\] g of water\.<\/p>/,
);
const finish = writes.filter((w) => w.table === 'content_drafts')[1];
expect(finish.filters).toContainEqual(['agent_state', 'writing']);
@@ -231,8 +232,9 @@ describe('startDraftWriting', () => {
value: expect.objectContaining({ feature: 'content' }),
});
const { prompt } = generateObject.mock.calls[0][0];
- expect(prompt).toContain('- ratio?');
- expect(prompt).toContain('- "pour over ratio"');
+ // The data, numbered as the agent cites it.
+ expect(prompt).toContain('- S1 ratio?');
+ expect(prompt).toContain('- S2 "pour over ratio"');
expect(prompt).toContain('- faq: FAQ with 5 questions — aim: 5');
expect(prompt).toContain('Page type: How-to guide: numbered steps to get one thing done');
});
@@ -413,9 +415,12 @@ describe('runDraftWriting on an existing page', () => {
kind: 'replace',
passage: 3,
before: 'good coffee',
- after: '15 g of coffee',
+ after: 'freshly ground coffee',
reason: 'answer the ratio search',
rules: ['faq'],
+ // From the fan-out it answers, S2 (CE-033).
+ sources: ['S2'],
+ marks: [{ words: 'freshly ground coffee', source: 'S2' }],
},
],
},
@@ -430,6 +435,8 @@ describe('runDraftWriting on an existing page', () => {
block_text: 'Use good coffee.',
before_text: 'good coffee',
position: 0,
+ sources: [{ kind: 'fanout', ref: 'pour over ratio', label: 'pour over ratio' }],
+ source_marks: [{ start: 0, end: 21, source: 0 }],
}),
]);
expect(generateObject.mock.calls[0][0].prompt).toContain(`[2] (p, LOCKED) ${QUOTED}`);
@@ -623,6 +630,32 @@ describe('Rewrite the page to these rules', () => {
});
});
+ it('keeps the data it wrote from, and no number without a source (CE-033)', async () => {
+ generateObject.mockResolvedValue({
+ object: {
+ html:
+ '<h1>Pour-over coffee</h1><p>[[KEEP 1]]</p><p>[[KEEP 2]]</p>' +
+ '<p>Brew it in 4 minutes; 87% of baristas agree, as "pour over ratio" asks.</p>',
+ reason: 'answered the ratio search',
+ sources: ['S2', 'S7'],
+ },
+ usage: { inputTokens: 900, outputTokens: 700 },
+ });
+ await expect(run()).resolves.toEqual({ rewritten: true });
+ const row = writes.find((w) => w.table === 'content_draft_suggestions').value;
+ // The fan-out it named; S7 isn't on the list.
+ expect(row.sources).toEqual([
+ { kind: 'fanout', ref: 'pour over ratio', label: 'pour over ratio' },
+ ]);
+ // 87% is in none of the data: a placeholder. A lone count stays; the
+ // kept table's 1:16 is the page's own.
+ expect(row.after_text).toContain(
+ '<p>Brew it in 4 minutes; [figure, source] of baristas agree, as "pour over ratio" asks.</p>',
+ );
+ expect(row.after_text).toContain('<td>1:16</td>');
+ expect(generateObject.mock.calls[0][0].system).toContain('Put the numbers (S1, S2…)');
+ });
+
it('keeps the page’s length when the Length rule is off', async () => {
answer('<h1>Pour-over</h1><p>[[KEEP 1]]</p><p>[[KEEP 2]]</p><p>Shorter.</p>');
await run({ rules: [{ key: 'faq', name: 'FAQ', detail: '' }] });
diff --git a/supabase/migrations/00248_content_suggestion_sources.sql b/supabase/migrations/00248_content_suggestion_sources.sql
new file mode 100644
index 000000000..fd50fdee7
--- /dev/null
+++ b/supabase/migrations/00248_content_suggestion_sources.sql
@@ -0,0 +1,41 @@
+-- ============================================================================
+-- 00248: the sources an agent's suggestion was written from
+-- ============================================================================
+-- Content Editor v1.1, CE-033: the Content Agent writes from the sources the
+-- Sources tab keeps (prompts, fan-outs, cited pages, Search Console queries),
+-- numbered, and says which ones each suggestion used and the words each one
+-- supports. The editor shows them as "Based on" chips under the suggestion
+-- and ¹ ² marks on its words; a chip opens its source in Sources. A number
+-- the agent adds with no source is not kept (content-sources.js).
+--
+-- sources: [{ "kind", "ref", "label" }], kind one of prompt, fanout,
+-- cited_page, gsc_query; ref as the Sources tab keys its row (a prompt's id,
+-- a normalized query, a page's address).
+--
+-- source_marks: [{ "start", "end", "source" }], offsets into the words a
+-- replace puts in (after_text) or an insert's HTML read as text; source is an
+-- index into sources. A page rewritten whole names its sources, with no marks.
+alter table public.content_draft_suggestions
+ add column if not exists sources jsonb
+ check (
+ sources is null
+ or (
+ jsonb_typeof(sources) = 'array'
+ and jsonb_array_length(sources) between 1 and 8
+ )
+ ),
+ add column if not exists source_marks jsonb
+ check (
+ source_marks is null
+ or (
+ kind in ('replace', 'insert')
+ and sources is not null
+ and jsonb_typeof(source_marks) = 'array'
+ and jsonb_array_length(source_marks) between 1 and 12
+ )
+ );
+
+comment on column public.content_draft_suggestions.sources is
+ 'The sources an agent suggestion was written from: [{ "kind", "ref", "label" }] (00248).';
+comment on column public.content_draft_suggestions.source_marks is
+ 'The words each source supports: [{ "start", "end", "source" }], offsets into after_text (a replace) or an insert''s text, source an index into sources (00248).';
diff --git a/supabase/schema.sql b/supabase/schema.sql
index d87e4dccd..b89bdb164 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -37166,6 +37166,51 @@ begin
end;
$$;
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00248_content_suggestion_sources.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00248: the sources an agent's suggestion was written from
+-- ============================================================================
+-- Content Editor v1.1, CE-033: the Content Agent writes from the sources the
+-- Sources tab keeps (prompts, fan-outs, cited pages, Search Console queries),
+-- numbered, and says which ones each suggestion used and the words each one
+-- supports. The editor shows them as "Based on" chips under the suggestion
+-- and ¹ ² marks on its words; a chip opens its source in Sources. A number
+-- the agent adds with no source is not kept (content-sources.js).
+--
+-- sources: [{ "kind", "ref", "label" }], kind one of prompt, fanout,
+-- cited_page, gsc_query; ref as the Sources tab keys its row (a prompt's id,
+-- a normalized query, a page's address).
+--
+-- source_marks: [{ "start", "end", "source" }], offsets into the words a
+-- replace puts in (after_text) or an insert's HTML read as text; source is an
+-- index into sources. A page rewritten whole names its sources, with no marks.
+alter table public.content_draft_suggestions
+ add column if not exists sources jsonb
+ check (
+ sources is null
+ or (
+ jsonb_typeof(sources) = 'array'
+ and jsonb_array_length(sources) between 1 and 8
+ )
+ ),
+ add column if not exists source_marks jsonb
+ check (
+ source_marks is null
+ or (
+ kind in ('replace', 'insert')
+ and sources is not null
+ and jsonb_typeof(source_marks) = 'array'
+ and jsonb_array_length(source_marks) between 1 and 12
+ )
+ );
+
+comment on column public.content_draft_suggestions.sources is
+ 'The sources an agent suggestion was written from: [{ "kind", "ref", "label" }] (00248).';
+comment on column public.content_draft_suggestions.source_marks is
+ 'The words each source supports: [{ "start", "end", "source" }], offsets into after_text (a replace) or an insert''s text, source an index into sources (00248).';
+
-- ─────────────────────────────────────────────────────────────────────────
-- migrations/00250_traffic_anonymous_visitors.sql
-- ─────────────────────────────────────────────────────────────────────────