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): plan the page in the brief behind CONTENT_BRIEF_RULES: essentials, angle, proof to gather, fan-outs left out and freshness, with Brief › Your input as sources (brief rules PR 5) (#1543)

Cihancc708ef2dc8c
diff --git a/server/src/lib/content-brief-eval.js b/server/src/lib/content-brief-eval.js
index b1f164d88..d19f851fa 100644
--- a/server/src/lib/content-brief-eval.js
+++ b/server/src/lib/content-brief-eval.js
@@ -98,14 +98,24 @@ function urlKey(url) {
/**
* A brief's fields as the judge sees them and as a quote is read in: the
- * goal, the audience, each heading and key point, version 2's answer, format
- * and facts (with the kind of source each needs and the page to check it
- * against), the keywords as one line; each with whether it's a heading.
+ * goal, the audience, version 2's essentials, angle and proof to gather,
+ * each heading and key point, a section's answer, format and facts (with the
+ * kind of source each needs and the source to check it against), the
+ * keywords as one line, the fan-outs left out and the freshness; each with
+ * whether it's a heading.
*/
function briefFields(brief) {
+ const fresh = brief.freshness;
return [
{ label: 'Goal: ', text: brief.goal, heading: false },
{ label: 'Audience: ', text: brief.audience, heading: false },
+ { label: 'TL;DR: ', text: brief.tldr, heading: false },
+ { label: 'Angle: ', text: brief.angle, heading: false },
+ ...(brief.proof ?? []).map((p) => ({
+ label: `Proof to gather (${p.kind}): `,
+ text: p.what,
+ heading: false,
+ })),
...brief.outline.flatMap((s) => [
{ label: 'H2: ', text: s.heading, heading: true },
...s.keyPoints.map((point) => ({ label: '- ', text: point, heading: false })),
@@ -118,6 +128,22 @@ function briefFields(brief) {
})),
]),
{ label: 'Keywords: ', text: brief.keywords.join(', '), heading: false },
+ {
+ label: 'Left out, for another page: ',
+ text: (brief.leftOut ?? []).join(', '),
+ heading: false,
+ },
+ {
+ label: 'Freshness: ',
+ text: [
+ fresh?.datedPoint && `date ${fresh.datedPoint}`,
+ fresh?.updatedLine && 'an "Updated" line',
+ fresh?.yearInTitle && 'the year in the title',
+ ]
+ .filter(Boolean)
+ .join('; '),
+ heading: false,
+ },
].filter((f) => f.text);
}
@@ -134,7 +160,9 @@ const PLACEHOLDERS = [NUMBER_PLACEHOLDER, NAME_PLACEHOLDER, QUOTE_PLACEHOLDER];
* The checks anyone can repeat, for one case's brief (after shapeBrief):
* * sections, those without a key point, headings past the editor's limit,
* and keywords past the ten the prompt asks for;
- * * fanoutCoverage: the share of the case's fan-outs an H2 answers;
+ * * fanoutCoverage: the share of the case's fan-outs an H2 answers, of
+ * those the brief keeps (version 2 leaves some to another page, as
+ * leftOut counts);
* * placeholders: the figures, names and quotes the guard took out;
* * invented (the gate, all 0): figures and names or quotes the guard let
* through that the case didn't give, and addresses it didn't list.
@@ -148,15 +176,18 @@ export function briefChecks(brief, c) {
[...c.sources.pages.map((p) => p.url), c.draft.source_url].filter(Boolean).map(urlKey),
);
const answered = new Set(brief.outline.map((s) => s.fanout).filter(Boolean));
+ const leftOut = new Set(brief.leftOut ?? []);
+ const kept = c.sources.fanouts.filter((f) => !leftOut.has(f.query));
return {
sections: brief.outline.length,
sectionsInRange: brief.outline.length >= SECTIONS.min && brief.outline.length <= SECTIONS.max,
emptySections: brief.outline.filter((s) => s.keyPoints.length === 0).length,
longHeadings: brief.outline.filter((s) => s.heading.length > HEADING_LIMITS.other).length,
extraKeywords: Math.max(0, brief.keywords.length - MAX_KEYWORDS),
- fanoutCoverage: c.sources.fanouts.length
- ? c.sources.fanouts.filter((f) => answered.has(f.query)).length / c.sources.fanouts.length
+ fanoutCoverage: kept.length
+ ? kept.filter((f) => answered.has(f.query)).length / kept.length
: null,
+ leftOut: c.sources.fanouts.length - kept.length,
placeholders: PLACEHOLDERS.reduce((n, p) => n + text.split(p).length - 1, 0),
invented: {
figures: found.flatMap((f) => f.figures),
diff --git a/server/src/lib/content-brief-eval.test.js b/server/src/lib/content-brief-eval.test.js
index 13a3edde9..05b3e5e41 100644
--- a/server/src/lib/content-brief-eval.test.js
+++ b/server/src/lib/content-brief-eval.test.js
@@ -186,6 +186,40 @@ describe('the checks anyone can repeat', () => {
expect(briefChecks(raw, FIRST).invented.figures).toEqual(['73']);
});
+ it('read the page’s plan too: essentials, angle, proof, fan-outs left out, freshness', () => {
+ const brief = shapeBrief(
+ {
+ ...GOOD,
+ tldr: 'A rolling forecast keeps cash visible, per www.made-up.example/tldr.',
+ angle: 'Ledgerly’s own variance data across customers',
+ proof: [{ kind: 'data', what: 'Average error before and after switching' }],
+ leftOut: [FIRST.sources.fanouts.at(-1).query],
+ datedPoint: 'The error figure, with its month',
+ },
+ FIRST,
+ );
+ const prompt = buildJudgePrompt(FIRST, brief);
+ expect(prompt).toContain('TL;DR: A rolling forecast keeps cash visible');
+ expect(prompt).toContain('Angle: Ledgerly’s own variance data across customers');
+ expect(prompt).toContain('Proof to gather (data): Average error before and after switching');
+ expect(prompt).toContain('Freshness: date The error figure, with its month');
+ expect(briefChecks(brief, FIRST).invented.urls).toEqual(['www.made-up.example/tldr']);
+ });
+
+ it('count coverage over the fan-outs the brief keeps: one left for another page isn’t missed', () => {
+ // GOOD answers all four of the case's fan-outs; without the first one's H2:
+ const [first] = FIRST.sources.fanouts;
+ const outline = GOOD.outline.filter((s) => s.fanout !== first.query);
+ const missed = briefChecks(shapeBrief({ ...GOOD, outline }, FIRST), FIRST);
+ expect(missed).toMatchObject({ fanoutCoverage: 0.75, leftOut: 0 });
+ // Left for another page, it isn't missed.
+ const left = briefChecks(
+ shapeBrief({ ...GOOD, outline, tldr: null, proof: [], leftOut: [first.query] }, FIRST),
+ FIRST,
+ );
+ expect(left).toMatchObject({ fanoutCoverage: 1, leftOut: 1 });
+ });
+
it('take an address the case gave: a cited page, or the live page', () => {
const live = CASES.find((c) => c.draft.method === 'optimize');
const brief = shapeBrief(
diff --git a/server/src/lib/content-brief.js b/server/src/lib/content-brief.js
index f352ce1f5..d037017f3 100644
--- a/server/src/lib/content-brief.js
+++ b/server/src/lib/content-brief.js
@@ -2,7 +2,13 @@ import { NoObjectGeneratedError, generateObject } from 'ai';
import { z } from 'zod';
import supabaseAdmin from '../config/supabase.js';
import { resolveModel } from './ai-provider.js';
-import { PAGE_TYPE_SECTION_FORMATS, pageTypeFormat, siteTypeLine } from './content-page-types.js';
+import {
+ PAGE_TYPE_FRESHNESS,
+ PAGE_TYPE_SECTION_FORMATS,
+ pageTypeFormat,
+ siteTypeLine,
+} from './content-page-types.js';
+import { inputSources, readDraftInputs } from './content-inputs.js';
import { getLanguageName } from './languages.js';
import {
RunStoppedError,
@@ -20,6 +26,7 @@ import {
knownNumbers,
numberSources,
placeholderNumbers,
+ sourceWords,
stripSourceIds,
todayText,
} from './content-sources.js';
@@ -126,10 +133,26 @@ export function briefRulesOn() {
* Version 2's limits, as the web reads them (web/src/lib/content/brief.ts
* BRIEF_V2_LIMITS, which content-brief.test.js reads to compare).
*/
-export const BRIEF_V2_LIMITS = { answer: 600, facts: 4, claim: 300, url: 2048 };
-/** How a section is best shown; the kind of source a fact needs (web brief.ts). */
+export const BRIEF_V2_LIMITS = {
+ answer: 600,
+ facts: 4,
+ claim: 300,
+ url: 2048,
+ tldr: 500,
+ angle: 500,
+ proof: 6,
+ proofWhat: 300,
+ leftOut: 20,
+ leftOutQuery: 300,
+ datedPoint: 300,
+};
+/**
+ * How a section is best shown; the kind of source a fact needs; the brand's
+ * own proof to gather, as Brief › Your input takes it (web brief.ts).
+ */
export const BRIEF_FORMATS = ['paragraphs', 'list', 'steps', 'table', 'faq'];
export const FACT_SOURCES = ['statistic', 'study', 'quote', 'example', 'official'];
+export const PROOF_KINDS = ['experience', 'data', 'case', 'test', 'quote'];
// No counts or lengths enforced on the model: a miss would fail the whole
// call (charged all the same). They are asked for here and cut afterwards.
@@ -155,8 +178,34 @@ export const outlineSchema = z.object({
keywords: z.array(z.string()).describe('Up to 10 keywords.'),
});
-/** Version 2's: each section with its answer, format and facts. */
+/**
+ * Version 2's: each section with its answer, format and facts; the page's
+ * essentials, angle, proof to gather, fan-outs left out and point to date.
+ */
export const outlineSchemaV2 = outlineSchema.extend({
+ tldr: z
+ .string()
+ .nullable()
+ .describe("What the page's essentials at its top must state: a note to the writer."),
+ angle: z
+ .string()
+ .nullable()
+ .describe("What this page can show that commodity pages can't: a note to the writer."),
+ proof: z
+ .array(
+ z.object({
+ kind: z.string().meta({ enum: PROOF_KINDS }).describe('Its kind.'),
+ what: z.string().describe('What to gather, as a note: never a figure.'),
+ }),
+ )
+ .describe("Up to 4 pieces of the brand's own proof to gather."),
+ leftOut: z
+ .array(z.string())
+ .describe('Fan-outs from the list that belong on another page, copied exactly.'),
+ datedPoint: z
+ .string()
+ .nullable()
+ .describe('What the page should date, as a note, or null when nothing in it dates.'),
outline: z
.array(
outlineSchema.shape.outline.element.extend({
@@ -212,10 +261,15 @@ Rules:
/** Version 2's rules (the brief rules, 2026), after version 1's. */
export const SYSTEM_PROMPT_V2 = `${SYSTEM_PROMPT}
- Answer first: in "answer", say what each section's first sentences must answer directly, as a note to the writer, with no word count: the rules give the length.
-- In "facts", name about one fact per section the page should state, with the kind of source it needs. In "source", give the number (S1…) of a cited page only when it is the one to check that fact against; you see only its address, never its words, so when unsure, null. Never write a figure of your own.
+- In "facts", name about one fact per section the page should state, with the kind of source it needs. In "source", give the number (S1…) of the person's input that gives it, or of a cited page only when it is the one to check that fact against (you see only its address, never its words); when unsure, null. Never write a figure of your own.
- The numbers (S1…) go in "source" only, never in another field.
- In "format", say how each section is best shown: a table for a comparison, numbered steps for a how-to, a list for picks or criteria, paragraphs for an explanation, faq for questions (its key points are the questions).
-- "format" and "sourceType" are keys: write them as listed, in English, whatever the brief's language.
+- Top first: in "tldr", say what the page's essentials at its top must state, as a note to the writer.
+- In "angle", say what this page can show that commodity pages can't: the brand's own data, cases, tests or first-hand experience. In "proof", list up to 4 of them to gather, each with its kind; one the person's input already gives, by its name.
+- One topic: in "leftOut", copy exactly the fan-outs listed that belong on another page; none when they all fit.
+- In "datedPoint", say what the page should date (a price, a figure with its month), or null when nothing in it dates.
+- The person's input, when listed, is their own: plan with it as given. Never invent a customer, a test, a quote or a figure beyond it.
+- "format", "sourceType" and a proof's "kind" are keys: write them as listed, in English, whatever the brief's language.
- Headings: each H2 about 8 to 15 words, under 90 characters.
- No keyword stuffing, and no wording made to trigger a citation: write for the reader.
- Follow the rules the page is written to, when listed.`;
@@ -263,7 +317,7 @@ export async function rebuildDraftBrief({ draftId, brandId, sources, rules = []
throw Object.assign(new Error('Draft not found'), { status: 404 });
}
- const [brandRes, promptsRes] = await Promise.all([
+ const [brandRes, promptsRes, inputRow] = await Promise.all([
supabaseAdmin
.from('brands')
.select(
@@ -278,6 +332,8 @@ export async function rebuildDraftBrief({ draftId, brandId, sources, rules = []
.in('id', sources.promptIds)
.eq('prompt_sets.brand_id', brandId)
: Promise.resolve({ data: [], error: null }),
+ // Brief › Your input (CE-048, Quality's second phase), with the brief rules on.
+ briefRulesOn() ? readDraftInputs(draftId) : Promise.resolve(null),
]);
if (brandRes.error) throw brandRes.error;
if (promptsRes.error) throw promptsRes.error;
@@ -285,6 +341,7 @@ export async function rebuildDraftBrief({ draftId, brandId, sources, rules = []
const prompts = (promptsRes.data ?? []).map((p) => p.text);
// The rules only with the brief rules on: the brief plans to them then, and may say their numbers.
const planTo = briefRulesOn() ? rules : [];
+ const inputs = inputSources(inputRow, brand.name);
if (!prompts.length && !sources.fanouts.length && !sources.queries.length) {
throw Object.assign(new Error('No prompts, fan-outs or queries to build from'), {
@@ -310,6 +367,7 @@ export async function rebuildDraftBrief({ draftId, brandId, sources, rules = []
prompts,
sources,
rules: planTo,
+ inputs,
run,
});
await finishRun(run, 'done');
@@ -325,7 +383,7 @@ export async function rebuildDraftBrief({ draftId, brandId, sources, rules = []
}
/** The rebuild itself, step by step: nothing is saved once it is stopped. */
-async function briefWithRun({ draft, draftId, brand, prompts, sources, rules, run }) {
+async function briefWithRun({ draft, draftId, brand, prompts, sources, rules, inputs, run }) {
const modelId = contentBriefModelId();
// Held on the budget before the call, so calls at once can't pass it.
const budget = await reserveAiBudget(brand.organization_id, {
@@ -349,7 +407,7 @@ async function briefWithRun({ draft, draftId, brand, prompts, sources, rules, ru
model: resolveModel(modelId),
schema: briefSchema(),
system: briefSystemPrompt(),
- prompt: buildBriefPrompt({ brand, draft, prompts, sources, rules }),
+ prompt: buildBriefPrompt({ brand, draft, prompts, sources, rules, inputs }),
abortSignal,
}),
);
@@ -368,7 +426,7 @@ async function briefWithRun({ draft, draftId, brand, prompts, sources, rules, ru
await advanceRun(run, 2);
const brief = {
- ...shapeBrief(object, { brand, draft, prompts, sources, rules }),
+ ...shapeBrief(object, { brand, draft, prompts, sources, rules, inputs }),
origin: 'rebuild',
builtAt: new Date().toISOString(),
builtFrom: {
@@ -402,40 +460,54 @@ export function shapeBrief(object, args) {
/**
* Under content_drafts.brief's 64 KB (00212), with room for jsonb's spaces:
- * past it, the facts' sources go, then the facts (a fact's source is a whole
- * address, 2 KB at most), so a brief charged for is one that saves.
+ * past it, the fan-outs left out go, then the facts' sources (a whole
+ * address, 2 KB at most), then the facts, so a brief charged for is one that
+ * saves.
*/
const BRIEF_BYTES = 60_000;
+const withFacts = (brief, strip) => ({
+ ...brief,
+ outline: brief.outline.map((section) => ({ ...section, facts: strip(section.facts ?? []) })),
+});
+const FIT_STEPS = [
+ (brief) => ({ ...brief, leftOut: [] }),
+ (brief) => withFacts(brief, (list) => list.map((f) => ({ ...f, source: null }))),
+ (brief) => withFacts(brief, () => []),
+];
function fitBrief(brief) {
const size = (b) => Buffer.byteLength(JSON.stringify(b));
- if (brief.version !== 2 || size(brief) <= BRIEF_BYTES) return brief;
- const without = (strip) => ({
- ...brief,
- outline: brief.outline.map((section) => ({ ...section, facts: strip(section.facts ?? []) })),
- });
- const unsourced = without((facts) => facts.map((f) => ({ ...f, source: null })));
- return size(unsourced) <= BRIEF_BYTES ? unsourced : without(() => []);
+ if (brief.version !== 2) return brief;
+ let fitted = brief;
+ for (const step of FIT_STEPS) {
+ if (size(fitted) <= BRIEF_BYTES) break;
+ fitted = step(fitted);
+ }
+ return fitted;
}
-function shapeWhole(object, { brand, draft, prompts, sources, rules }) {
- const guard = briefGuard({ brand, draft, prompts, sources, rules });
- // Version 2's (a model answer with them): each section's answer, format and facts.
- const v2 = object.outline.some((section) => 'answer' in section || 'facts' in section);
- const byId = v2 ? new Map(briefNumbered(sources).map((n) => [n.id, n])) : null;
+function shapeWhole(object, { brand, draft, prompts, sources, rules, inputs = [] }) {
+ const guard = briefGuard({ brand, draft, prompts, sources, rules, inputs });
+ // Version 2's (a model answer with them): each section's plan, the page's.
+ const v2 =
+ 'tldr' in object ||
+ 'proof' in object ||
+ object.outline.some((section) => 'answer' in section || 'facts' in section);
+ const byId = v2 ? new Map(briefNumbered(sources, inputs).map((n) => [n.id, n])) : null;
// Version 2's numbers (S1…) belong in a fact's source only: taken out of the words.
const words = v2 ? (text) => stripSourceIds(text, byId.size) : (text) => text;
+ const outline = mapOutline(
+ object.outline.map((section) => ({
+ ...section,
+ heading: guard.heading(words(section.heading)),
+ keyPoints: (section.keyPoints ?? []).map((point) => guard.text(words(point))),
+ ...(v2 ? sectionPlan(section, guard, byId, words) : {}),
+ })),
+ sources.fanouts,
+ );
return {
goal: clip(guard.text(words(object.goal)), BRIEF_LIMITS.goal),
audience: clip(guard.text(words(object.audience)), BRIEF_LIMITS.audience),
- outline: mapOutline(
- object.outline.map((section) => ({
- ...section,
- heading: guard.heading(words(section.heading)),
- keyPoints: (section.keyPoints ?? []).map((point) => guard.text(words(point))),
- ...(v2 ? sectionPlan(section, guard, byId, words) : {}),
- })),
- sources.fanouts,
- ),
+ outline,
keywords: [
...new Set(
object.keywords
@@ -445,7 +517,57 @@ function shapeWhole(object, { brand, draft, prompts, sources, rules }) {
.filter(Boolean),
),
].slice(0, BRIEF_LIMITS.keywords),
- ...(v2 ? { version: 2 } : {}),
+ ...(v2 ? { version: 2, ...pagePlan(object, { guard, words, outline, sources, draft }) } : {}),
+ };
+}
+
+/**
+ * The page's plan of version 2, cut to the web's limits and guarded as the
+ * rest: its essentials (tldr) and angle; the brand's own proof to gather, of
+ * a kind the web knows; the fan-outs left out for another page, each one the
+ * person kept that no H2 answers, as listed; its freshness, the point to
+ * date as the model names it, the "Updated" line and the year in the title
+ * by page type (PAGE_TYPE_FRESHNESS).
+ */
+function pagePlan(object, { guard, words, outline, sources, draft }) {
+ const L = BRIEF_V2_LIMITS;
+ const note = (text, max) => clip(guard.text(words(text ?? '')), max) || null;
+ const proof = (object.proof ?? [])
+ .map((p) => {
+ const kind = keyOf(p?.kind);
+ const what = clip(guard.text(words(p?.what ?? '')), L.proofWhat);
+ return PROOF_KINDS.includes(kind) && what ? { kind, what } : null;
+ })
+ .filter(Boolean)
+ .slice(0, L.proof);
+ const kept = fanoutMatcher(sources.fanouts);
+ const answered = new Set(outline.map((section) => section.fanout).filter(Boolean));
+ const leftOut = [
+ ...new Set(
+ (object.leftOut ?? [])
+ .map((query) => kept(String(query ?? ''))?.query)
+ .filter((query) => query && !answered.has(query)),
+ ),
+ ]
+ .map((query) => query.slice(0, L.leftOutQuery))
+ .slice(0, L.leftOut);
+ const dates = Object.hasOwn(PAGE_TYPE_FRESHNESS, draft.page_type ?? '')
+ ? PAGE_TYPE_FRESHNESS[draft.page_type]
+ : null;
+ const datedPoint = note(object.datedPoint, L.datedPoint);
+ return {
+ tldr: note(object.tldr, L.tldr),
+ angle: note(object.angle, L.angle),
+ proof,
+ leftOut,
+ freshness:
+ datedPoint || dates
+ ? {
+ datedPoint,
+ updatedLine: dates?.updatedLine ?? false,
+ yearInTitle: dates?.yearInTitle ?? false,
+ }
+ : null,
};
}
@@ -490,12 +612,12 @@ function sectionPlan(section, guard, byId, words) {
}
/**
- * The cited pages, numbered as the writer numbers its data (S1…,
- * numberSources): version 2's facts name the one to check them against by
- * it. Only pages: a prompt, a fan-out or a query is a question, not a source.
+ * The cited pages, then Brief › Your input, numbered as the writer numbers
+ * its data (S1…, numberSources): version 2's facts name their source by it.
+ * Only those: a prompt, a fan-out or a query is a question, not a source.
*/
-export function briefNumbered(sources) {
- return numberSources({ pages: sources.pages });
+export function briefNumbered(sources, inputs = []) {
+ return numberSources({ pages: sources.pages, inputs });
}
/**
@@ -509,8 +631,8 @@ export function briefNumbered(sources) {
* one, as a placeholder can't be searched for; `found` lists what a text
* adds, read the same way (the brief eval's gate).
*/
-export function briefGuard({ brand, draft, prompts, sources, rules }) {
- const { given, known, people } = briefKnown({ brand, draft, prompts, sources, rules });
+export function briefGuard({ brand, draft, prompts, sources, rules, inputs }) {
+ const { given, known, people } = briefKnown({ brand, draft, prompts, sources, rules, inputs });
// The names and quotes a text may have: a question in quotes in it too.
const askedIn = (words) => {
const questions = [...words.matchAll(QUOTED_QUESTION)].map((m) => m[1]);
@@ -540,9 +662,10 @@ export function briefGuard({ brand, draft, prompts, sources, rules }) {
/**
* What a brief is built from (`given`), and the numbers (`known`) and the
* names and quotes (`people`) it may say: briefGuard's, and the brief eval's.
- * The rules it plans to are among them ("aim: 60 words").
+ * The rules it plans to are among them ("aim: 60 words"), and the person's
+ * own input, word for word.
*/
-export function briefKnown({ brand, draft, prompts, sources, rules = [] }) {
+export function briefKnown({ brand, draft, prompts, sources, rules = [], inputs = [] }) {
const given = [
brand?.name,
brand?.industry,
@@ -554,6 +677,7 @@ export function briefKnown({ brand, draft, prompts, sources, rules = [] }) {
...sources.headings,
String(sources.length),
...rules.flatMap((rule) => [rule.name, rule.detail]),
+ ...inputs.map(sourceWords),
];
return { given, known: knownNumbers(...given, todayText()), people: knownPeople(...given) };
}
@@ -565,14 +689,10 @@ export function briefKnown({ brand, draft, prompts, sources, rules = [] }) {
* left empty goes, long text is shortened, and the lists are capped.
*/
export function mapOutline(outline, fanouts) {
- // As listed first; then without its quotes, as the model may copy it.
- const asListed = new Map(fanouts.map((f) => [norm(f.query), f]));
- const unquoted = new Map(fanouts.map((f) => [fanoutKey(f.query), f]));
+ const kept = fanoutMatcher(fanouts);
return outline
.map((section) => {
- const fanout = section.fanout
- ? (asListed.get(norm(section.fanout)) ?? unquoted.get(fanoutKey(section.fanout)))
- : undefined;
+ const fanout = section.fanout ? kept(section.fanout) : undefined;
const platform =
fanout && fanout.platforms.includes(section.platform)
? section.platform
@@ -595,14 +715,32 @@ export function mapOutline(outline, fanouts) {
.slice(0, BRIEF_LIMITS.sections);
}
+/**
+ * The kept fan-out a text names, or undefined: as listed first, then without
+ * its quotes, as the model may copy it.
+ */
+function fanoutMatcher(fanouts) {
+ const asListed = new Map(fanouts.map((f) => [norm(f.query), f]));
+ const unquoted = new Map(fanouts.map((f) => [fanoutKey(f.query), f]));
+ return (text) => asListed.get(norm(text)) ?? unquoted.get(fanoutKey(text));
+}
+
/** What the model is told: the brand, the page, and the sources kept. */
-export function buildBriefPrompt({ brand, draft, prompts, sources, rules = [] }) {
+export function buildBriefPrompt({ brand, draft, prompts, sources, rules = [], inputs = [] }) {
const list = (items) => (items.length ? items.map((item) => `- ${item}`).join('\n') : '- none');
const v2 = briefRulesOn();
- // With the brief rules on, each cited page by its number (S1…), for the facts' sources.
+ // With the brief rules on, each cited page and each piece of the person's
+ // input by its number (S1…), for the facts' sources.
+ const numbered = v2 ? briefNumbered(sources, inputs) : [];
const pages = v2
- ? briefNumbered(sources).map((n) => `${n.id}: ${n.label} (${n.detail})`)
+ ? numbered
+ .filter((n) => n.kind === 'cited_page')
+ .map((n) => `${n.id}: ${n.label} (${n.detail})`)
: sources.pages.map((p) => `${p.url} (${p.kind})`);
+ // Without a note (a quote's address, a day): a fact cites the input by its number.
+ const given = numbered
+ .filter((n) => n.kind === 'input')
+ .map((n) => `${n.id} "${n.label}": ${n.detail}`);
const leans =
v2 && Object.hasOwn(PAGE_TYPE_SECTION_FORMATS, draft.page_type ?? '')
? PAGE_TYPE_SECTION_FORMATS[draft.page_type]
@@ -628,6 +766,6 @@ ${list(sources.queries)}
Pages AI cites for these prompts today:
${list(pages)}
-
+${given.length ? `\nThe person's own input for this page (Brief › Your input):\n${list(given)}\n` : ''}
${sources.headings.length ? `The page's headings now:\n${list(sources.headings)}\n\n` : ''}Write the brief in ${getLanguageName(brand?.language)}.`;
}
diff --git a/server/src/lib/content-brief.test.js b/server/src/lib/content-brief.test.js
index f0010042a..9c0de6d94 100644
--- a/server/src/lib/content-brief.test.js
+++ b/server/src/lib/content-brief.test.js
@@ -68,6 +68,7 @@ const {
BRIEF_FORMATS,
BRIEF_V2_LIMITS,
FACT_SOURCES,
+ PROOF_KINDS,
SYSTEM_PROMPT,
SYSTEM_PROMPT_V2,
briefGuard,
@@ -595,6 +596,7 @@ describe('the brief prompt', () => {
describe('the brief rules (2026), behind CONTENT_BRIEF_RULES', () => {
afterEach(() => {
delete process.env.CONTENT_BRIEF_RULES;
+ vi.unstubAllEnvs();
});
it('asks as before while they are off: the same rules, schema and prompt', async () => {
@@ -724,11 +726,17 @@ describe('the brief rules (2026), behind CONTENT_BRIEF_RULES', () => {
{ type: 'null' },
]);
expect(section.facts.items.properties.sourceType.enum).toEqual(FACT_SOURCES);
+ expect(json.properties.proof.items.properties.kind.enum).toEqual(PROOF_KINDS);
expect(SYSTEM_PROMPT_V2).toContain('write them as listed, in English');
// A model that writes "Table" or a translated key still answers: read by key afterwards.
const read = outlineSchemaV2.safeParse({
goal: 'g',
audience: 'a',
+ tldr: null,
+ angle: null,
+ proof: [{ kind: 'Fallstudie', what: 'w' }],
+ leftOut: [],
+ datedPoint: null,
outline: [
{
heading: 'h',
@@ -745,6 +753,153 @@ describe('the brief rules (2026), behind CONTENT_BRIEF_RULES', () => {
expect(read.success).toBe(true);
});
+ it('plans the page: its essentials, angle, proof to gather, fan-outs left out and freshness', async () => {
+ process.env.CONTENT_BRIEF_RULES = 'true';
+ generateObject.mockResolvedValue({
+ object: {
+ goal: 'g',
+ audience: 'a',
+ tldr: 'Say which machine wins for 73% of home baristas (S1).',
+ angle: ' Our own side-by-side pull tests. ',
+ proof: [
+ { kind: 'Test', what: 'Shot times on each machine' },
+ { kind: 'rumour', what: 'What people say' },
+ { kind: 'case', what: ' ' },
+ { kind: 'data', what: 'Returns by model' },
+ ],
+ leftOut: [
+ '“home espresso grinder”',
+ 'Best espresso machine under 500',
+ 'made up search',
+ 'home espresso grinder',
+ ],
+ datedPoint: 'Each price, with its month',
+ outline: [
+ {
+ heading: 'The best espresso machines under $500',
+ keyPoints: [],
+ fanout: 'Best espresso machine under 500',
+ platform: null,
+ answer: null,
+ format: null,
+ facts: [],
+ },
+ ],
+ keywords: [],
+ },
+ usage: { inputTokens: 10, outputTokens: 5 },
+ });
+ const brief = await rebuildDraftBrief({ draftId: DRAFT, brandId: BRAND, sources: sources() });
+ expect(brief).toMatchObject({
+ version: 2,
+ // Guarded and cut as the rest: a figure it wasn't given is a placeholder, its number goes.
+ tldr: `Say which machine wins for ${NUMBER_PLACEHOLDER} of home baristas.`,
+ angle: 'Our own side-by-side pull tests.',
+ // Kinds the web knows, read by key; none left empty.
+ proof: [
+ { kind: 'test', what: 'Shot times on each machine' },
+ { kind: 'data', what: 'Returns by model' },
+ ],
+ // Fan-outs the person kept that no H2 answers, as listed, each once.
+ leftOut: ['home espresso grinder'],
+ // A buying guide dates: an "Updated" line and the year in its title.
+ freshness: { datedPoint: 'Each price, with its month', updatedLine: true, yearInTitle: true },
+ });
+ });
+
+ it('plans no freshness for a page that doesn’t date and names nothing to date', async () => {
+ process.env.CONTENT_BRIEF_RULES = 'true';
+ rows.content_drafts.page_type = 'feature_page';
+ generateObject.mockResolvedValue({
+ object: {
+ goal: 'g',
+ audience: 'a',
+ tldr: null,
+ angle: null,
+ proof: [],
+ leftOut: [],
+ datedPoint: null,
+ outline: [],
+ keywords: [],
+ },
+ usage: { inputTokens: 10, outputTokens: 5 },
+ });
+ const brief = await rebuildDraftBrief({ draftId: DRAFT, brandId: BRAND, sources: sources() });
+ expect(brief).toMatchObject({ version: 2, tldr: null, angle: null, proof: [], leftOut: [] });
+ expect(brief.freshness).toBeNull();
+ });
+
+ it('numbers the person’s input after the cited pages, for the facts’ sources, and knows its words', async () => {
+ process.env.CONTENT_BRIEF_RULES = 'true';
+ vi.stubEnv('CONTENT_QUALITY_PHASE', '2');
+ rows.content_draft_inputs = {
+ experience: 'We pulled 40 shots on each machine.',
+ data: [
+ {
+ name: 'Returns by model',
+ rows: [
+ ['Model', 'Returns'],
+ ['Bambino', '4.2%'],
+ ],
+ },
+ ],
+ ansvisor_data: [],
+ quotes: [],
+ };
+ generateObject.mockResolvedValue({
+ object: {
+ goal: 'g',
+ audience: 'a',
+ tldr: 'The Bambino had 4.2% returns.',
+ angle: null,
+ proof: [{ kind: 'experience', what: 'The 40 shots we pulled' }],
+ leftOut: [],
+ datedPoint: null,
+ outline: [
+ {
+ heading: 'Machines',
+ keyPoints: [],
+ fanout: null,
+ platform: null,
+ answer: null,
+ format: null,
+ facts: [{ claim: 'Returns by model', sourceType: 'statistic', source: 'S3' }],
+ },
+ ],
+ keywords: [],
+ },
+ usage: { inputTokens: 10, outputTokens: 5 },
+ });
+ const brief = await rebuildDraftBrief({ draftId: DRAFT, brandId: BRAND, sources: sources() });
+ const prompt = generateObject.mock.calls[0][0].prompt;
+ expect(prompt).toContain('- S1: https://www.reddit.com/r/espresso/x (forum)');
+ expect(prompt).toContain(
+ 'The person\'s own input for this page (Brief › Your input):\n- S2 "We pulled 40 shots on each machine.": Their experience, first-hand',
+ );
+ expect(prompt).toContain('- S3 "Returns by model": Their own data, a table');
+ // Their figures are given: kept, not placeholders.
+ expect(brief.tldr).toBe('The Bambino had 4.2% returns.');
+ expect(brief.proof).toEqual([{ kind: 'experience', what: 'The 40 shots we pulled' }]);
+ expect(brief.outline[0].facts[0].source).toEqual({
+ kind: 'input',
+ ref: 'data:1',
+ label: 'Returns by model',
+ });
+ });
+
+ it('reads no input while the brief rules are off', async () => {
+ vi.stubEnv('CONTENT_QUALITY_PHASE', '2');
+ rows.content_draft_inputs = {
+ experience: 'We pulled 40 shots.',
+ data: [],
+ ansvisor_data: [],
+ quotes: [],
+ };
+ await rebuildDraftBrief({ draftId: DRAFT, brandId: BRAND, sources: sources() });
+ expect(filters.some((f) => f.table === 'content_draft_inputs')).toBe(false);
+ expect(generateObject.mock.calls[0][0].prompt).not.toContain('Your input');
+ });
+
it('leaves version 1’s words as they were: numbers aren’t taken out, the rules aren’t known', async () => {
generateObject.mockResolvedValue({
object: {
@@ -805,6 +960,48 @@ describe('the brief rules (2026), behind CONTENT_BRIEF_RULES', () => {
expect(brief.outline.every((s) => s.facts.every((f) => f.source === null))).toBe(true);
});
+ it('lets the fan-outs left out go first, when that is enough to fit', async () => {
+ process.env.CONTENT_BRIEF_RULES = 'true';
+ const long = 'https://www.reddit.com/r/espresso/' + 'x'.repeat(2000);
+ const queries = Array.from({ length: 20 }, (_, i) =>
+ `${String.fromCharCode(97 + i)} `.repeat(150),
+ );
+ const section = (i) => ({
+ heading: `Machines ${String.fromCharCode(97 + i)}`,
+ keyPoints: [],
+ fanout: null,
+ platform: null,
+ answer: null,
+ format: null,
+ facts: Array(4).fill({ claim: 'c'.repeat(300), sourceType: 'study', source: 'S1' }),
+ });
+ generateObject.mockResolvedValue({
+ object: {
+ goal: 'g',
+ audience: 'a',
+ tldr: null,
+ angle: null,
+ proof: [],
+ leftOut: queries,
+ datedPoint: null,
+ outline: Array.from({ length: 5 }, (_, i) => section(i)),
+ keywords: [],
+ },
+ usage: { inputTokens: 10, outputTokens: 5 },
+ });
+ const brief = await rebuildDraftBrief({
+ draftId: DRAFT,
+ brandId: BRAND,
+ sources: sources({
+ pages: [{ url: long, kind: 'forum' }],
+ fanouts: queries.map((query) => ({ query: query.trim(), platforms: ['chatgpt'] })),
+ }),
+ });
+ expect(Buffer.byteLength(JSON.stringify(brief))).toBeLessThan(64_000);
+ expect(brief.leftOut).toEqual([]);
+ expect(brief.outline[0].facts[0].source).toMatchObject({ kind: 'cited_page', ref: long });
+ });
+
it('lets the facts go too when the brief is still too big without their sources', async () => {
process.env.CONTENT_BRIEF_RULES = 'true';
// Three bytes a character: the answers fit, the facts don't beside them.
@@ -868,7 +1065,7 @@ describe('the brief rules (2026), behind CONTENT_BRIEF_RULES', () => {
it.skipIf(!webHasV2)('writes version 2 to the web’s limits, kinds and sample', () => {
const limits = webText.match(/export const BRIEF_V2_LIMITS = \{([\s\S]*?)\} as const/)[1];
const limit = (key) => Number(limits.match(new RegExp(`\\b${key}: (\\d+)`))[1]);
- for (const key of ['answer', 'facts', 'claim', 'url']) {
+ for (const key of Object.keys(BRIEF_V2_LIMITS)) {
expect(BRIEF_V2_LIMITS[key], key).toBe(limit(key));
}
const kinds = (name) =>
@@ -879,6 +1076,7 @@ describe('the brief rules (2026), behind CONTENT_BRIEF_RULES', () => {
].map((m) => m[1]);
expect(BRIEF_FORMATS).toEqual(kinds('BRIEF_FORMATS'));
expect(FACT_SOURCES).toEqual(kinds('FACT_SOURCES'));
+ expect(PROOF_KINDS).toEqual(kinds('PROOF_KINDS'));
const sample = JSON.parse(
readFileSync(
new URL('../../../web/src/lib/content/__fixtures__/brief-v2.json', import.meta.url),
@@ -899,6 +1097,11 @@ describe('the brief rules (2026), behind CONTENT_BRIEF_RULES', () => {
.match(/export const DRAFT_SOURCE_KINDS = \[([^\]]*)\]/)[1]
.matchAll(/'([a-z_]+)'/g),
].map((m) => m[1]);
- for (const n of briefNumbered(sources())) expect(draftKinds).toContain(n.kind);
+ // …and Brief › Your input, which a suggestion keeps as 'input' too.
+ expect(webSources).toMatch(/SUGGESTION_SOURCE_KINDS = \[\.\.\.DRAFT_SOURCE_KINDS, 'input'\]/);
+ const inputs = [{ kind: 'input', ref: 'experience', label: 'We tested', detail: 'We tested' }];
+ for (const n of briefNumbered(sources(), inputs)) {
+ expect([...draftKinds, 'input']).toContain(n.kind);
+ }
});
});
diff --git a/server/src/lib/content-page-types.js b/server/src/lib/content-page-types.js
index e680e51ce..3ac869a91 100644
--- a/server/src/lib/content-page-types.js
+++ b/server/src/lib/content-page-types.js
@@ -60,6 +60,20 @@ export const PAGE_TYPE_SECTION_FORMATS = {
definition: 'the term defined in its first sentence, then paragraphs',
};
+/**
+ * The page types whose picks, prices or terms date (brief rules 2026,
+ * freshness): each shows an "Updated" line; a ranked or compared one has the
+ * year in its title too ("Best espresso machines in 2026").
+ */
+export const PAGE_TYPE_FRESHNESS = {
+ best_of: { updatedLine: true, yearInTitle: true },
+ buying_guide: { updatedLine: true, yearInTitle: true },
+ alternatives: { updatedLine: true, yearInTitle: true },
+ comparison: { updatedLine: true, yearInTitle: true },
+ pricing: { updatedLine: true, yearInTitle: false },
+ policy: { updatedLine: true, yearInTitle: false },
+};
+
/** Kinds of site (brands.site_type, 00205), as web/src/lib/content/page-types.ts has them. */
export const SITE_TYPES = ['b2b', 'ecommerce', 'b2c'];
diff --git a/server/src/lib/content-page-types.test.js b/server/src/lib/content-page-types.test.js
index e9cbadeff..4ec2c8551 100644
--- a/server/src/lib/content-page-types.test.js
+++ b/server/src/lib/content-page-types.test.js
@@ -2,6 +2,8 @@ import { readFileSync } from 'node:fs';
import { afterEach, describe, expect, it, vi } from 'vitest';
import {
PAGE_TYPE_FORMATS,
+ PAGE_TYPE_FRESHNESS,
+ PAGE_TYPE_SECTION_FORMATS,
SITE_PAGE_TYPES,
SITE_TYPES,
siteTypeLine,
@@ -10,6 +12,21 @@ import {
siteTypeOf,
} from './content-page-types.js';
+describe('the brief’s plan by page type', () => {
+ it('leans and dates only page types the editor has', () => {
+ for (const type of [
+ ...Object.keys(PAGE_TYPE_SECTION_FORMATS),
+ ...Object.keys(PAGE_TYPE_FRESHNESS),
+ ]) {
+ expect(PAGE_TYPE_FORMATS, type).toHaveProperty(type);
+ }
+ // A page with the year in its title shows when it was updated too.
+ for (const [type, dates] of Object.entries(PAGE_TYPE_FRESHNESS)) {
+ expect(dates.updatedLine || !dates.yearInTitle, type).toBe(true);
+ }
+ });
+});
+
describe('pageTypeFormat', () => {
it('names a page type as the person picks it, with its format', () => {
expect(pageTypeFormat('solution_page')).toBe(