Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(content): tell the Content Agent which fan-outs to use (#1373)
Cihanafae781033b2
diff --git a/server/src/lib/content-agent.js b/server/src/lib/content-agent.jsindex 0582e5d6a..f2ed8434c 100644--- a/server/src/lib/content-agent.js+++ b/server/src/lib/content-agent.js@@ -44,9 +44,11 @@ export const HEADING_LIMITS = { h1: 70, other: 90 };export const headingLimit = (tag) => (tag === 'h1' ? HEADING_LIMITS.h1 : HEADING_LIMITS.other);/** The headings rule both agent prompts give the model (fix rules, Start Agent). */-export const HEADING_RULE = `- A heading stays a heading: one short line, an H1 up to ${HEADING_LIMITS.h1} characters and other headings up to ${HEADING_LIMITS.other}. Never write an answer, a sentence or a FAQ into a heading's replace; to answer under a heading, insert a paragraph after it.`;+/** The fan-outs rule both agent prompts give the model: the ones named, in their words. */+export const FANOUT_RULE = `- Fan-outs are the searches AI engines run for the page's questions. For each fan-out a rule names, in its words ("aeo tracker" → "What is an AEO tracker?"), not questions of your own: fanoutH2 wants an H2, fanoutFaq a question ending in "?" under the FAQ heading. Add it as its own question: after the paragraph that ends an existing answer, insert a heading at the level of the FAQ's other questions (an H3 under an H2 FAQ) and a paragraph that answers it. Reword an existing question into a fan-out's words only when its answer still answers it, replacing that question alone. One question per heading: never add a question to a heading. Call a change a fan-out answer only when it uses a fan-out listed.`;+/** The links rule both agent prompts give the model: only the URLs listed, never invented. */export const LINK_RULE = `- Links: link only to a URL listed under the pages or sources you may link to, copied exactly, as <a href="URL">the words it explains</a>, in a replace's "after" or in an insert. Cite a source by linking the words it supports. Never invent a URL, never link a heading, and when no listed page fits, add no link.`;@@ -115,6 +117,7 @@ Rules for your suggestions:- An insert adds new blocks after a passage, as simple HTML (h2, h3, p, ul, ol, li, strong, em, and a for links).${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].- Keep the page's voice and change as little as each rule needs. At most ${MAX_AGENT_SUGGESTIONS} suggestions.@@ -241,6 +244,11 @@ const isHeading = (tag) => /^h[1-6]$/.test(tag);const QUESTION_AND_ANSWER = /^([\s\S]+?(?:\?(?=\s)|?))\s*(\S[\s\S]*)$/;/** How an answer ends: a sentence. */const ANSWER_END = /[.!。!]$/;+/** What follows a heading's question may open with another question, not an answer. */+const OPENS_WITH_QUESTION = /^[^.!?。!?]*(?:\?(?=\s|$)|?)/;+/** Each question's end: "?" before a space or at the end, or a full-width "?". */+const QUESTION_MARKS = /\?(?=\s|$)|?/g;+const questionsIn = (text) => (text.match(QUESTION_MARKS) ?? []).length;/** Where the first block of a cleaned HTML starts. */const BLOCK_START = /<(?:h[2-4]|p|ul|ol|li)>/;@@ -253,6 +261,17 @@ export function growsPastLimit(passage, before, words) {return then > headingLimit(passage.tag) && then > now;}+/**+ * Whether a replace makes a heading ask more than one question: an FAQ+ * question with a fan-out's question added to it ("What is X? What is an+ * AEO tracker?"). A new question goes in as its own heading and answer.+ */+export function asksMoreThanOne(passage, before, words) {+ if (!isHeading(passage.tag)) return false;+ const then = questionsIn(passage.text.replace(before, () => words));+ return then > 1 && then > questionsIn(passage.text);+}+/** A paragraph holding `text`, escaped. */function paragraph(text) {const $ = cheerio.load('<p></p>', null, false);@@ -293,10 +312,13 @@ export function splitReplace(after, tag, links = null) {// A question and its answer ("What is X? X is …"): the answer goes under// the heading first, before any blocks that came with it. A subtitle that// fits ("What is AEO? The Complete Guide") isn't one: an answer ends a- // sentence. Past the heading's limit, the rest is never the heading's.+ // sentence. Past the heading's limit, the rest is never the heading's,+ // unless it opens with a second question: that one isn't an answer, and+ // the heading asking both is dropped (asksMoreThanOne).const answered = words.match(QUESTION_AND_ANSWER);if (answered &&+ !OPENS_WITH_QUESTION.test(answered[2]) &&(words.length > headingLimit(tag) ||(ANSWER_END.test(answered[2]) && answered[2].length >= MIN_ANSWER_CHARS))) {@@ -313,10 +335,10 @@ export function splitReplace(after, tag, links = null) {* HTML cleaned and not empty; the rules named kept to the ones sent, and* each change once. A replace that carries blocks, or an answer on a* heading, is split into a replace and an insert after it (splitReplace);- * one that would still grow a heading past its headingLimit is dropped (a- * long heading may still be shortened). 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.+ * 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.*/export function keepSuggestions(raw, passages, lockedKeys, ruleKeys, links = null) {const kept = [];@@ -356,7 +378,13 @@ export function keepSuggestions(raw, passages, lockedKeys, ruleKeys, links = nulconst wordLinks = split.links.slice(0, MAX_LINKS);// Linking words the passage already has is a change too.const changed = words && (words !== before || wordLinks.length > 0);- if (changed && (words.length > 2000 || growsPastLimit(passage, before, words))) continue;+ if (+ changed &&+ (words.length > 2000 ||+ growsPastLimit(passage, before, words) ||+ asksMoreThanOne(passage, before, words))+ )+ continue;changes = [changed && {id: `replace:${passage.text}:${before}`,diff --git a/server/src/lib/content-agent.test.js b/server/src/lib/content-agent.test.jsindex 0ee750e31..955cd4368 100644--- a/server/src/lib/content-agent.test.js+++ b/server/src/lib/content-agent.test.js@@ -53,6 +53,7 @@ vi.mock('./content-links.js', async (importOriginal) => ({}));const {+ asksMoreThanOne,buildFixPrompt,cleanInsertHtml,draftPassages,@@ -319,6 +320,36 @@ describe('a replace on a heading', () => {expect(keep({ after: 'What is LLM SEO '.repeat(10) })).toEqual([]);});+ it('drops one that adds a second question to a heading, and keeps a question reworded', () => {+ const faq = draftPassages(+ '<h2>FAQ</h2><h3>What is AEO?</h3><p>Answer engine optimization.</p>',+ );+ const run = (after) =>+ keepSuggestions(+ [suggestion({ passage: 2, before: 'What is AEO?', after, rules: ['fanoutFaq'] })],+ faq,+ new Set(),+ new Set(['fanoutFaq']),+ );+ // A fan-out's question added to the one there, short, past the limit or answered.+ expect(run('What is AEO? What is an AEO tracker?')).toEqual([]);+ expect(+ run(+ 'What is AEO? What is an AEO tracker? An AEO tracker is a tool that reads many AI engines for you.',+ ),+ ).toEqual([]);+ expect(+ run(`What is AEO? How does ${'an AEO tracker read many engines and '.repeat(3)}work?`),+ ).toEqual([]);+ // The question reworded into the fan-out's words.+ expect(run('What is an AEO tracker?')).toEqual([+ expect.objectContaining({ kind: 'replace', after_text: 'What is an AEO tracker?' }),+ ]);+ // A heading that already asks two may still change.+ expect(asksMoreThanOne({ tag: 'h3', text: 'Why AEO? Why now?' }, 'now', 'today')).toBe(false);+ expect(asksMoreThanOne({ tag: 'p', text: 'Why?' }, 'Why?', 'Why? How?')).toBe(false);+ });+it('holds an H1 to 70 characters and other headings to 90, unless they get shorter', () => {expect(HEADING_LIMITS).toEqual({ h1: 70, other: 90 });const h1 = { tag: 'h1', text: 'Guide' };@@ -399,6 +430,16 @@ describe('a replace on a heading', () => {// Past the heading's limit the rest goes under it, a full stop or not.const long = `What is LLM SEO? ${'LLM SEO optimizes pages for large language models '.repeat(2)}`;expect(splitReplace(long, 'h2').words).toBe('What is LLM SEO?');+ // A second question is no answer, with its own answer or not: it stays,+ // for keepSuggestions to drop.+ const two = `What is LLM SEO? How does ${'LLM SEO read many engines and '.repeat(3)}work?`;+ expect(splitReplace(two, 'h2')).toMatchObject({ words: two, blocks: '' });+ const answered =+ 'What is AEO? What is an AEO tracker? An AEO tracker is a tool that reads many AI engines for you.';+ expect(splitReplace(answered, 'h3')).toMatchObject({ words: answered, blocks: '' });+ // An answer that ends on a question still goes under the heading.+ const why = `What is LLM SEO? ${'LLM SEO optimizes pages for large language models. '.repeat(2)}Why care?`;+ expect(splitReplace(why, 'h2').words).toBe('What is LLM SEO?');});it('moves blocks sent with a paragraph replace after it', () => {@@ -542,6 +583,9 @@ describe('links to the pages and sources given', () => {// Only the rule asked for: no outbound list.expect(prompt).not.toContain('Sources you may link to');expect(system).toContain('Never invent a URL');+ // The fan-outs a rule names, in their words (B).+ expect(system).toContain('fanoutH2 wants an H2, fanoutFaq a question');+ expect(system).toContain('One question per heading: never add a question to a heading.');expect(result.count).toBe(1);const batch = writes.find((w) => w.table === 'content_draft_suggestions');expect(batch.value[0]).toMatchObject({diff --git a/server/src/lib/content-writer.js b/server/src/lib/content-writer.jsindex e06558aed..cab74f636 100644--- a/server/src/lib/content-writer.js+++ b/server/src/lib/content-writer.js@@ -4,6 +4,7 @@ import { z } from 'zod';import supabaseAdmin from '../config/supabase.js';import { resolveModel } from './ai-provider.js';import {+ FANOUT_RULE,HEADING_RULE,LINK_RULE,MAX_AGENT_SUGGESTIONS,@@ -97,6 +98,7 @@ How to write:- Follow the outline when there is one; each H2 answers one of the questions or AI searches given.- 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].- Plain text in every field: no HTML, no Markdown.- Write in the language asked for.`;@@ -109,6 +111,7 @@ Rules for your suggestions:- An insert adds new blocks after a passage, as simple HTML (h2, h3, p, ul, ol, li, strong, em, and a for links): a missing section, a direct answer, an FAQ.${HEADING_RULE}${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].diff --git a/server/src/lib/content-writer.test.js b/server/src/lib/content-writer.test.jsindex 7cae2fca5..bbdc33009 100644--- a/server/src/lib/content-writer.test.js+++ b/server/src/lib/content-writer.test.js@@ -353,6 +353,10 @@ describe('runDraftWriting on a new page', () => {// The answer is charged to the hold; nothing is left to release after.expect(budget.charge).toHaveBeenCalledTimes(1);expect(budget.release).toHaveBeenCalled();+ // The fan-outs a rule names, in their words, on a new page too (B).+ expect(generateObject.mock.calls[0][0].system).toContain(+ '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.',+ );expect(rpcCalls).toEqual([['content_draft_snapshot', { p_draft_id: DRAFT, p_origin: 'agent_before' }],]);@@ -433,6 +437,9 @@ describe('runDraftWriting on an existing page', () => {);// Links only to the pages and sources listed (A); none asked for here.expect(generateObject.mock.calls[0][0].system).toContain('Never invent a URL');+ expect(generateObject.mock.calls[0][0].system).toContain(+ 'Call a change a fan-out answer only when it uses a fan-out listed',+ );expect(readLinkTargets).toHaveBeenCalledWith(expect.objectContaining({ draftId: DRAFT, ruleKeys: new Set(['faq']) }),);diff --git a/web/messages/en.json b/web/messages/en.jsonindex 12b287de3..0b6e0c938 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -4092,7 +4092,8 @@"agent": {"aim": "aim","now": "now",- "phrases": "phrases found"+ "phrases": "phrases found",+ "fanouts": "fan-outs to use, in their words"},"saveMine": "Save as my rules","reset": "Reset",diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsxindex 6d6cd08cc..af1aec277 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx@@ -63,7 +63,7 @@ import {import { PAGE_READ_DELAY_MS, draftTitleFromDoc, safeLinkHref } from '@/lib/content/editor';import { JsonLd } from '@/lib/content/json-ld-node';import { detectPageType } from '@/lib/content/page-types';-import { aiTracesFound, lengthWarns, openRulesForAgent } from '@/lib/content/rules';+import { aiTracesFound, fanoutsToUse, lengthWarns, openRulesForAgent } from '@/lib/content/rules';import { saveBlob } from '@/lib/download';import { cn } from '@/lib/utils';import { AgentBar } from './_agent-bar';@@ -587,21 +587,26 @@ export function DraftEditor({}const pageText = editor.getText({ blockSeparator: '\n' });const request = {- rules: open.map(({ rule, status }) => ({- key: rule.key,- name: tRules(`names.${rule.key}`),- detail: [- rule.current- ? `${tRules('agent.aim')}: ${rule.current}${rule.unit ? ` ${tRules(`units.${rule.unit}`)}` : ''}`- : null,- `${tRules('agent.now')}: ${ruleStatusDetail(tStatus, status)}`,- rule.key === 'aiTraces'- ? `${tRules('agent.phrases')}: ${aiTracesFound(pageText).join(', ')}`- : null,- ]- .filter(Boolean)- .join(' · '),- })),+ rules: open.map(({ rule, status }) => {+ const fanouts = fanoutsToUse(status);+ return {+ key: rule.key,+ name: tRules(`names.${rule.key}`),+ detail: [+ rule.current+ ? `${tRules('agent.aim')}: ${rule.current}${rule.unit ? ` ${tRules(`units.${rule.unit}`)}` : ''}`+ : null,+ `${tRules('agent.now')}: ${ruleStatusDetail(tStatus, status)}`,+ rule.key === 'aiTraces'+ ? `${tRules('agent.phrases')}: ${aiTracesFound(pageText).join(', ')}`+ : null,+ // Which fan-outs, so it writes those rather than questions of its own.+ fanouts ? `${tRules('agent.fanouts')}: ${fanouts}` : null,+ ]+ .filter(Boolean)+ .join(' · '),+ };+ }),textRules: rules.textRules.filter(({ rule }) => rule.on).map(({ rule }) => rule.text),locked: (() => {const locks = citedLocks(editor.state);diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsxindex b830ea863..d518cb480 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx@@ -1941,6 +1941,35 @@ describe('the side panel', () => {);});+ it('names the fan-outs the page doesn’t use yet, so the agent writes those', async () => {+ getContentDraft.mockResolvedValue(traced);+ getDraftSources.mockResolvedValue({+ data: {+ prompts: [],+ fanouts: [{ query: 'pipeline forecasting', platforms: ['copilot-web'], searched: 2 }],+ citedPages: [],+ gscQueries: [],+ brandDomains: [],+ competitorDomains: [],+ },+ choices: [],+ });+ fixDraftRules.mockResolvedValue({ count: 0 });+ await openRules();++ await act(async () => panelButton('Apply rules with Agent').click());+ await act(async () => {});++ expect(fixDraftRules.mock.calls[0][2].rules).toContainEqual(+ expect.objectContaining({+ key: 'fanoutH2',+ detail: expect.stringContaining(+ 'fan-outs to use, in their words: "pipeline forecasting"',+ ),+ }),+ );+ });+it('says a full batch is the most one run makes, to run it again (C)', async () => {getContentDraft.mockResolvedValue(traced);const full = Array.from({ length: 8 }, (_, i) => ({diff --git a/web/src/lib/content/agent-suggestions.test.ts b/web/src/lib/content/agent-suggestions.test.tsindex 8651b8039..8eded28d1 100644--- a/web/src/lib/content/agent-suggestions.test.ts+++ b/web/src/lib/content/agent-suggestions.test.ts@@ -177,6 +177,38 @@ describe('a replace on a heading', () => {expect(dropped).toEqual([{ index: 0, reason: 'heading_too_long' }]);});+ it('says when a heading would ask a second question, and keeps a question reworded', () => {+ const faq = draftPassages(+ '<h2>FAQ</h2><h3>What is AEO?</h3><p>Answer engine optimization.</p>',+ );+ const run = (after: string) =>+ keepAgentSuggestions(+ [{ kind: 'replace', passage: 2, before: 'What is AEO?', after, reason: 'fan-out' }],+ faq,+ new Set(),+ );+ // A fan-out's question added to the one there.+ expect(run('What is AEO? What is an AEO tracker?')).toEqual({+ kept: [],+ dropped: [{ index: 0, reason: 'heading_two_questions' }],+ });+ // Past the limit, or with its answer, the second question isn't moved+ // under the first as if it answered it.+ expect(+ run(`What is AEO? How does ${'an AEO tracker read many engines and '.repeat(3)}work?`)+ .dropped,+ ).toEqual([{ index: 0, reason: 'heading_two_questions' }]);+ expect(+ run(+ 'What is AEO? What is an AEO tracker? An AEO tracker is a tool that reads many AI engines for you.',+ ).dropped,+ ).toEqual([{ index: 0, reason: 'heading_two_questions' }]);+ // The question reworded into the fan-out's words.+ expect(run('What is an AEO tracker?').kept).toEqual([+ expect.objectContaining({ kind: 'replace', after_text: 'What is an AEO tracker?' }),+ ]);+ });+it('holds an H1 to 70 characters and other headings to 90, unless they get shorter', () => {const run = (html: string, before: string, after: string) =>keepAgentSuggestions(diff --git a/web/src/lib/content/agent-suggestions.ts b/web/src/lib/content/agent-suggestions.tsindex 1a1c08991..42069a5d2 100644--- a/web/src/lib/content/agent-suggestions.ts+++ b/web/src/lib/content/agent-suggestions.ts@@ -1,7 +1,7 @@import sanitizeHtml from 'sanitize-html';import { passageKey } from './cited-passages';import { linkKey } from './link-targets';-import { growsPastLimit, headingLimit, type SuggestionLink } from './suggestions';+import { asksMoreThanOne, growsPastLimit, headingLimit, type SuggestionLink } from './suggestions';/*** An agent's suggestions through the editor API (CE-022): the same contract@@ -145,6 +145,8 @@ const MIN_ANSWER_CHARS = 40;const QUESTION_AND_ANSWER = /^([\s\S]+?(?:\?(?=\s)|?))\s*(\S[\s\S]*)$/;/** How an answer ends: a sentence. */const ANSWER_END = /[.!。!]$/;+/** What follows a heading's question may open with another question, not an answer. */+const OPENS_WITH_QUESTION = /^[^.!?。!?]*(?:\?(?=\s|$)|?)/;/** Where the first block of a cleaned HTML starts. */const BLOCK_START = /<(?:h[2-4]|p|ul|ol|li)>/;@@ -190,10 +192,13 @@ export function splitReplace(// A question and its answer ("What is X? X is …"): the answer goes under// the heading first, before any blocks that came with it. A subtitle that// fits ("What is AEO? The Complete Guide") isn't one: an answer ends a- // sentence. Past the heading's limit, the rest is never the heading's.+ // sentence. Past the heading's limit, the rest is never the heading's,+ // unless it opens with a second question: that one isn't an answer, and+ // the heading asking both is dropped (asksMoreThanOne).const answered = words.match(QUESTION_AND_ANSWER);if (answered &&+ !OPENS_WITH_QUESTION.test(answered[2]) &&(words.length > headingLimit(levelOf(tag)) ||(ANSWER_END.test(answered[2]) && answered[2].length >= MIN_ANSWER_CHARS))) {@@ -234,7 +239,8 @@ export type DroppedReason =| 'empty'| 'duplicate'| 'too_many'- | 'heading_too_long';+ | 'heading_too_long'+ | 'heading_two_questions';/*** The suggestions the editor can apply: a passage that exists; a replace's@@ -242,7 +248,8 @@ export type DroppedReason =* insert's HTML cleaned and not empty; each change once. A replace that* carries blocks, or an answer on a heading, is split into a replace and an* insert after it (splitReplace); one that would still grow a heading past- * its limit (growsPastLimit) is dropped.+ * its limit (growsPastLimit), or make it ask a second question+ * (asksMoreThanOne), is dropped.*/export function keepAgentSuggestions(raw: AgentSuggestionInput[],@@ -296,6 +303,17 @@ export function keepAgentSuggestions(if (!changed && !blocks) return drop('no_change');if (changed && words.length > 2000) return drop('no_change');if (!passage.text.includes(before)) return drop('not_in_passage');+ // A second question first: shortening it would still leave two.+ if (+ changed &&+ isHeading(passage.tag) &&+ asksMoreThanOne(+ passage.text,+ passage.text.replace(before, () => words),+ )+ ) {+ return drop('heading_two_questions');+ }if (changed &&isHeading(passage.tag) &&diff --git a/web/src/lib/content/agent-write.test.ts b/web/src/lib/content/agent-write.test.tsindex 8a019b7dc..155586a4d 100644--- a/web/src/lib/content/agent-write.test.ts+++ b/web/src/lib/content/agent-write.test.ts@@ -18,6 +18,7 @@ vi.mock('@/lib/actions/content-drafts', () => ({}));const { agentWriteRequest } = await import('./agent-write');+const { fanoutsToUse } = await import('./rules');const data: DraftSourcesData = {prompts: [@@ -84,6 +85,39 @@ describe('agentWriteRequest', () => {expect(request.locked).toEqual([]);});+ it('gives the fan-out rules the fan-outs the page doesn’t use yet', async () => {+ const seen: Record<string, string | null> = {};+ const request = await agentWriteRequest(+ draft({ bodyHtml: '<h1>Burr grinders</h1><h2>Hand grinders</h2>' }),+ (rule, status) => {+ seen[rule.key] = status ? fanoutsToUse(status) : null;+ return { name: rule.key, detail: '' };+ },+ );+ expect(request.rules.map((rule) => rule.key)).toContain('fanoutH2');+ // A page the agent writes anew uses none of them yet: named, in their words.+ expect(seen.fanoutH2).toBe('"burr grinder under 200"');+ expect(seen.fanoutFaq).toBe('"burr grinder under 200"');+ // Only the fan-out rules carry a status.+ expect(seen.length).toBeNull();+ });++ it('names only what an existing page doesn’t use yet', async () => {+ const seen: Record<string, string | null> = {};+ await agentWriteRequest(+ draft({+ method: 'optimize',+ sourceUrl: 'https://acme.example/grinders',+ bodyHtml: '<h1>Burr grinders</h1><h2>The best burr grinder under 200</h2>',+ }),+ (rule, status) => {+ seen[rule.key] = status ? fanoutsToUse(status) : null;+ return { name: rule.key, detail: '' };+ },+ );+ expect(seen.fanoutH2).toBeNull();+ });+it('locks what AI quotes on an existing page, and takes the editor’s rules as given', async () => {getCitedPassages.mockResolvedValue([{ key: 'burrs grind evenly', platforms: [] }]);const rules = activeRules(ruleSet('product_page'), NO_DRAFT_RULES).filter((rule) =>diff --git a/web/src/lib/content/agent-write.ts b/web/src/lib/content/agent-write.tsindex 4bf20b85b..de3f2591d 100644--- a/web/src/lib/content/agent-write.ts+++ b/web/src/lib/content/agent-write.ts@@ -7,11 +7,15 @@ import { isPageType, type DraftMethod } from './drafts';import {NOT_FOR_AGENT,activeRules,+ checkRule,effectiveRules,+ fanoutsToUse,+ readPage,ruleLength,ruleSet,type ActiveRule,type DraftRules,+ type RuleStatus,} from './rules';/**@@ -32,23 +36,40 @@ export interface AgentWriteRequest {/** The server's limit on rules (content-writer.js writeDraftInput). */const MAX_AGENT_RULES = 60;-/** A rule as the agent reads it: its name, and what it asks. */-export type RuleDescriber = (rule: ActiveRule) => { name: string; detail: string };+/**+ * A rule as the agent reads it: its name, and what it asks; with its status+ * on the page, the fan-outs a fan-out rule still needs.+ */+export type RuleDescriber = (+ rule: ActiveRule,+ status?: RuleStatus,+) => { name: string; detail: string };/** Rules in the reader's words, as Fix open rules sends them. */export function useRuleDescriber(): RuleDescriber {const t = useTranslations('contentEditor.editor.rules');return useCallback(- (rule: ActiveRule) => ({- name: t(`names.${rule.key}`),- detail: rule.current- ? `${t('agent.aim')}: ${rule.current}${rule.unit ? ` ${t(`units.${rule.unit}`)}` : ''}`- : '',- }),+ (rule: ActiveRule, status?: RuleStatus) => {+ const fanouts = status ? fanoutsToUse(status) : null;+ return {+ name: t(`names.${rule.key}`),+ detail: [+ rule.current+ ? `${t('agent.aim')}: ${rule.current}${rule.unit ? ` ${t(`units.${rule.unit}`)}` : ''}`+ : null,+ fanouts ? `${t('agent.fanouts')}: ${fanouts}` : null,+ ]+ .filter(Boolean)+ .join(' · '),+ };+ },[t],);}+/** The rules whose status names the fan-outs to use. */+const FANOUT_RULES = new Set(['fanoutH2', 'fanoutFaq']);+/** The page's headings and paragraphs, as the editor's passages. */function pagePassages(html: string): string[] {const doc = new DOMParser().parseFromString(html, 'text/html');@@ -103,16 +124,28 @@ export async function agentWriteRequest(const textRules =inEffect?.textRules ?? effective.textRules.filter((rule) => rule.on).map((rule) => rule.text);const length = ruleLength(rules, setType);+ const sources = read+ ? rebuildSources(read.data, read.choices, {+ title: draft.title,+ sourceUrl: draft.sourceUrl,+ html: draft.bodyHtml,+ length,+ })+ : { promptIds: [], fanouts: [], pages: [], queries: [], headings: [], length };+ // The fan-out rules name the fan-outs the page doesn't use yet: an existing+ // page's own; a page the agent writes anew starts from none of them.+ const page = readPage(draft.method === 'optimize' ? (draft.bodyHtml ?? '') : '', 0);+ const ctx = {+ brandDomains: [],+ competitorDomains: [],+ fanouts: sources.fanouts.map((f) => f.query),+ };return {- sources: read- ? rebuildSources(read.data, read.choices, {- title: draft.title,- sourceUrl: draft.sourceUrl,- html: draft.bodyHtml,- length,- })- : { promptIds: [], fanouts: [], pages: [], queries: [], headings: [], length },- rules: rules.slice(0, MAX_AGENT_RULES).map((rule) => ({ key: rule.key, ...describe(rule) })),+ sources,+ rules: rules.slice(0, MAX_AGENT_RULES).map((rule) => ({+ key: rule.key,+ ...describe(rule, FANOUT_RULES.has(rule.key) ? checkRule(rule, page, ctx) : undefined),+ })),textRules,locked: (cited ?? []).map((passage) => passage.key),};diff --git a/web/src/lib/content/rules.test.ts b/web/src/lib/content/rules.test.tsindex df1842c55..fa3269707 100644--- a/web/src/lib/content/rules.test.ts+++ b/web/src/lib/content/rules.test.ts@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';import {NO_DRAFT_RULES,NOT_FOR_AGENT,+ fanoutsToUse,openRulesForAgent,activeRules,effectiveRules,@@ -248,11 +249,13 @@ describe('fan-outs and keywords', () => {'2',),).toEqual({ state: 'ok' });+ // It names the ones still to use, so the agent writes those.expect(check('fanoutH2', '<h2>Best espresso machines under $500</h2>')).toEqual({state: 'bad',code: 'partOf',count: 1,of: 3,+ missing: ['home espresso grinder', 'espresso machine reviews 2026'],});expect(checkRule(rule('fanoutH2'), page('<h2>x</h2>'), { ...ctx, fanouts: [] })).toEqual({state: 'info',@@ -267,8 +270,65 @@ describe('fan-outs and keywords', () => {expect(check('faq', faq)).toEqual({ state: 'bad', code: 'partOf', count: 2, of: 5 });expect(check('faq', faq, '2')).toEqual({ state: 'ok' });expect(check('faq', '<h2>Questions</h2>')).toEqual({ state: 'bad', code: 'missing' });- expect(check('fanoutFaq', faq)).toEqual({ state: 'bad', code: 'partOf', count: 1, of: 3 });- expect(check('fanoutFaq', '<p>x</p>')).toEqual({ state: 'bad', code: 'needsFaq' });+ expect(check('fanoutFaq', faq)).toEqual({+ state: 'bad',+ code: 'partOf',+ count: 1,+ of: 3,+ missing: ['best espresso machine under 500', 'espresso machine reviews 2026'],+ });+ // Fewer fan-outs than questions asked: using each one meets it, and the+ // one still needed is named.+ const two = { ...ctx, fanouts: ['home espresso grinder', 'espresso machine reviews 2026'] };+ expect(checkRule(rule('fanoutFaq'), page(faq), two)).toEqual({+ state: 'bad',+ code: 'partOf',+ count: 1,+ of: 2,+ missing: ['espresso machine reviews 2026'],+ });+ const both =+ '<h2>FAQ</h2><h3>Which home espresso grinder should I buy?</h3><p>The Baratza.</p>' ++ '<h3>Where are the espresso machine reviews of 2026?</h3><p>Here.</p>';+ expect(checkRule(rule('fanoutFaq'), page(both), two)).toEqual({ state: 'ok' });+ // Different fan-outs count, not questions: two asking the same one are one.+ const same =+ '<h2>FAQ</h2><h3>Which home espresso grinder should I buy?</h3><p>The Baratza.</p>' ++ '<h3>Is a home espresso grinder worth it?</h3><p>Yes.</p>';+ expect(checkRule(rule('fanoutFaq'), page(same), two)).toEqual({+ state: 'bad',+ code: 'partOf',+ count: 1,+ of: 2,+ missing: ['espresso machine reviews 2026'],+ });+ // One question that uses two of them counts both.+ const one =+ '<h2>FAQ</h2><h3>Which home espresso grinder do the espresso machine reviews 2026 pick?</h3><p>The Baratza.</p>';+ expect(checkRule(rule('fanoutFaq'), page(one), two)).toEqual({ state: 'ok' });+ // No FAQ yet: still the fan-outs its questions should use.+ expect(check('fanoutFaq', '<p>x</p>')).toEqual({+ state: 'bad',+ code: 'needsFaq',+ missing: [+ 'best espresso machine under 500',+ 'home espresso grinder',+ 'espresso machine reviews 2026',+ ],+ });+ });++ it('quotes the fan-outs still to use for the agent, as many as fit', () => {+ const status = check('fanoutH2', '<h2>x</h2>');+ expect(fanoutsToUse(status)).toBe(+ '"best espresso machine under 500"; "home espresso grinder"; "espresso machine reviews 2026"',+ );+ expect(fanoutsToUse(status, 40)).toBe('"best espresso machine under 500"');+ // One that doesn't fit doesn't stop a shorter one after it.+ expect(fanoutsToUse(status, 60)).toBe(+ '"best espresso machine under 500"; "home espresso grinder"',+ );+ expect(fanoutsToUse({ state: 'ok' })).toBeNull();});it('counts the keywords on the page', () => {@@ -564,6 +624,13 @@ describe('lengthConflict', () => {expect(lengthConflict(statuses({ length: { value: '800' }, faq: { on: false } }), 3)?.need,).toBe(600 + 450 + 100);+ // Two fan-outs: two fan-out H2s and two fan-out questions at most.+ expect(+ lengthConflict(+ statuses({ length: { value: '500' }, faq: { on: false } }, ctx.fanouts.slice(0, 2)),+ 2,+ )?.need,+ ).toBe(400 + 300 + 100);// No fan-outs: no fan-out H2s or fan-out questions to fit.expect(lengthConflict(statuses({ length: { value: '600' } }, []), 0)?.need).toBe(750 + 100);expect(diff --git a/web/src/lib/content/rules.ts b/web/src/lib/content/rules.tsindex f5769a2d4..5746d30ec 100644--- a/web/src/lib/content/rules.ts+++ b/web/src/lib/content/rules.ts@@ -573,12 +573,21 @@ const isQuestion = (b: PageBlock) => b.text.trim().endsWith('?');export type RuleStatus =| { state: 'ok' }| { state: 'bad'; code: 'over' | 'found'; count: number }- | { state: 'bad'; code: 'partOf'; count: number; of: number }+ | {+ state: 'bad';+ code: 'partOf';+ count: number;+ of: number;+ /** The fan-outs still to use, the most searched first (fanoutH2, fanoutFaq). */+ missing?: string[];+ }| { state: 'bad'; code: 'current'; count: number }/** Out of the Length rule's band, as it reads (lengthBand). */| { state: 'bad'; code: 'short' | 'long'; count: number; min: number; max: number }| { state: 'bad'; code: 'words'; count: number }- | { state: 'bad'; code: 'missing' | 'noH2' | 'needsFaq' | 'notSet' }+ | { state: 'bad'; code: 'missing' | 'noH2' | 'notSet' }+ /** No FAQ yet: the fan-outs its questions should use, the most searched first. */+ | { state: 'bad'; code: 'needsFaq'; missing?: string[] }| {state: 'info';code: 'aiCheck' | 'needsFeed' | 'noFanouts' | 'addKeywords' | 'notHowTo' | 'englishOnly';@@ -710,6 +719,25 @@ const atLeast = (have: number, want: number): RuleStatus =>*/export const NOT_FOR_AGENT = new Set(['oneH1']);+/**+ * The fan-outs a rule still needs (fanoutH2, fanoutFaq), quoted for the+ * agent, the most searched first and as many as fit in `max` characters:+ * the rule's detail it is sent has room for 500. Null when there are none.+ */+export function fanoutsToUse(status: RuleStatus, max = 300): string | null {+ if (status.state !== 'bad' || !('missing' in status) || !status.missing?.length) return null;+ const quoted: string[] = [];+ let length = 0;+ for (const fanout of status.missing) {+ const item = `"${fanout}"`;+ // One too long for what's left: a shorter one after it may still fit.+ if (length + item.length > max) continue;+ quoted.push(item);+ length += item.length + 2;+ }+ return quoted.length ? quoted.join('; ') : null;+}+/*** The rules on that the page doesn't meet (of `only`, when given): the ones* the Content Agent is asked to fix, and those it can't.@@ -786,7 +814,17 @@ export function checkRule(rule: ActiveRule, page: PageRead, ctx: RuleContext): Rconst top = ctx.fanouts.slice(0, n);if (!top.length) return { state: 'info', code: 'noFanouts' };const h2s = blocks.filter((b) => b.tag === 'h2');- return atLeast(top.filter((f) => h2s.some((h) => carries(f, h.text))).length, top.length);+ // Which ones, so the agent writes those, not H2s of its own.+ const missing = top.filter((f) => !h2s.some((h) => carries(f, h.text)));+ return missing.length+ ? {+ state: 'bad',+ code: 'partOf',+ count: top.length - missing.length,+ of: top.length,+ missing,+ }+ : { state: 'ok' };}case 'faq':case 'buyingFaq': {@@ -796,10 +834,22 @@ export function checkRule(rule: ActiveRule, page: PageRead, ctx: RuleContext): R}case 'fanoutFaq': {const questions = faqQuestions(blocks);- if (!questions) return { state: 'bad', code: 'needsFaq' };+ if (!questions) {+ // A new page has no FAQ yet: still name the fan-outs it should ask.+ const missing = ctx.fanouts.slice(0, n);+ return missing.length+ ? { state: 'bad', code: 'needsFaq', missing }+ : { state: 'bad', code: 'needsFaq' };+ }if (!ctx.fanouts.length) return { state: 'info', code: 'noFanouts' };- const used = questions.filter((q) => ctx.fanouts.some((f) => carries(f, q))).length;- return atLeast(used, n);+ // Different fan-outs the questions use, as fanoutH2 counts its H2s: no+ // more than there are, and each one still needed is named.+ const unused = ctx.fanouts.filter((f) => !questions.some((q) => carries(f, q)));+ const used = ctx.fanouts.length - unused.length;+ const of = Math.min(n, ctx.fanouts.length);+ if (used >= of) return { state: 'ok' };+ // The most searched ones no question uses yet, as many as are still needed.+ return { state: 'bad', code: 'partOf', count: used, of, missing: unused.slice(0, of - used) };}case 'keywords': {const wanted = list(rule.current);@@ -960,7 +1010,12 @@ export function lengthConflict(if (!Number.isFinite(target) || target <= 0) return null;const need =Math.min(asked('fanoutH2'), fanouts) * LEAST_SECTION +- Math.max(asked('faq'), asked('buyingFaq'), fanouts ? asked('fanoutFaq') : 0) * LEAST_QUESTION ++ Math.max(+ asked('faq'),+ asked('buyingFaq'),+ fanouts ? Math.min(asked('fanoutFaq'), fanouts) : 0,+ ) *+ LEAST_QUESTION +(asked('summary') ? LEAST_SUMMARY : 0);// The page holds them all already: it shows they fit.if (counted.every((status) => status.state === 'ok')) return null;diff --git a/web/src/lib/content/suggestions.test.ts b/web/src/lib/content/suggestions.test.tsindex e5ea6b5f4..1b253181b 100644--- a/web/src/lib/content/suggestions.test.ts+++ b/web/src/lib/content/suggestions.test.ts@@ -1,5 +1,5 @@import { describe, expect, it } from 'vitest';-import { growsPastLimit, headingLimit, suggestionLinks } from './suggestions';+import { asksMoreThanOne, growsPastLimit, headingLimit, suggestionLinks } from './suggestions';/*** How long an agent's change may make a heading: an H1 up to 70 characters,@@ -22,6 +22,19 @@ describe('growsPastLimit', () => {});});+/** One question per heading: a new question goes in as its own heading. */+describe('asksMoreThanOne', () => {+ it('holds a heading to one question, unless it already asked more', () => {+ expect(asksMoreThanOne('What is AEO?', 'What is AEO? What is an AEO tracker?')).toBe(true);+ expect(asksMoreThanOne('What is AEO?', 'What is AEO? What is an AEO tracker?')).toBe(true);+ expect(asksMoreThanOne('What is AEO?', 'What is an AEO tracker?')).toBe(false);+ // A subtitle, or "?" inside a word, is no second question.+ expect(asksMoreThanOne('AEO', 'AEO or SEO? Which matters more in 2026')).toBe(false);+ expect(asksMoreThanOne('Guide', 'What?No guide?')).toBe(false);+ expect(asksMoreThanOne('Why AEO? Why now?', 'Why AEO? Why today?')).toBe(false);+ });+});+/** A replace's links (00240), as the editor may put them on. */describe('suggestionLinks', () => {it('keeps safe links inside the words, in order, not overlapping', () => {diff --git a/web/src/lib/content/suggestions.ts b/web/src/lib/content/suggestions.tsindex b6f8d86ad..c15c29da8 100644--- a/web/src/lib/content/suggestions.ts+++ b/web/src/lib/content/suggestions.ts@@ -57,6 +57,21 @@ export function growsPastLimit(level: number, now: number, then: number): booleareturn then > headingLimit(level) && then > now;}+/** Each question's end: "?" before a space or at the end, or a full-width "?". */+const QUESTION_MARKS = /\?(?=\s|$)|?/g;+const questionsIn = (text: string) => (text.match(QUESTION_MARKS) ?? []).length;++/**+ * Whether changing a heading from `now` to `then` makes it ask more than one+ * question: an FAQ question with a fan-out's question added to it. A new+ * question goes in as its own heading and answer. The same as+ * asksMoreThanOne in server/src/lib/content-agent.js.+ */+export function asksMoreThanOne(now: string, then: string): boolean {+ const questions = questionsIn(then);+ return questions > 1 && questions > questionsIn(now);+}+/** A link on a replace's new words: afterText from start to end, linked to href. */export interface SuggestionLink {start: number;diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.tsindex 1e3c22379..b05e4e327 100644--- a/web/src/lib/mcp/server.ts+++ b/web/src/lib/mcp/server.ts@@ -1688,7 +1688,7 @@ export function createMcpServer(auth: McpAuthContext): McpServer {server.registerTool('suggest_content_changes',{- description: `Leave changes on a draft for a person to accept or reject in the editor — never applied by the agent. Read the draft with get_content_draft first: each suggestion names a passage by its number. A replace changes words in that passage ("before" copied exactly as the passage has it, "after" as plain text); an insert adds blocks after it ("after" as simple HTML: h2, h3, p, ul, ol, li, strong, em). Either may link words as <a href="URL">words</a>, but only to a URL in get_content_draft's link_targets: any other link is unwrapped to its words, and a heading never keeps a link. A heading stays one line (an H1 up to ${HEADING_LIMITS.h1} characters, others up to ${HEADING_LIMITS.other}): to answer under it, insert a paragraph after it (an answer or blocks sent in a heading's replace are moved into an insert after it). Never change a locked passage. While a person still has the draft's open suggestions to decide, no new ones are taken: wait until get_content_draft lists none. At most ${MAX_API_SUGGESTIONS}; ones the editor can't apply come back in "dropped" with the reason (no_passage, locked, not_in_passage, no_change, empty, duplicate, too_many, heading_too_long).`,+ description: `Leave changes on a draft for a person to accept or reject in the editor — never applied by the agent. Read the draft with get_content_draft first: each suggestion names a passage by its number. A replace changes words in that passage ("before" copied exactly as the passage has it, "after" as plain text); an insert adds blocks after it ("after" as simple HTML: h2, h3, p, ul, ol, li, strong, em). Either may link words as <a href="URL">words</a>, but only to a URL in get_content_draft's link_targets: any other link is unwrapped to its words, and a heading never keeps a link. A heading stays one line (an H1 up to ${HEADING_LIMITS.h1} characters, others up to ${HEADING_LIMITS.other}): to answer under it, insert a paragraph after it (an answer or blocks sent in a heading's replace are moved into an insert after it). One question per heading: to add a question, insert it as its own heading with its answer. Never change a locked passage. While a person still has the draft's open suggestions to decide, no new ones are taken: wait until get_content_draft lists none. At most ${MAX_API_SUGGESTIONS}; ones the editor can't apply come back in "dropped" with the reason (no_passage, locked, not_in_passage, no_change, empty, duplicate, too_many, heading_too_long, heading_two_questions).`,inputSchema: {draft_id: relaxedUuid.describe('Draft UUID.'),...suggestionsShape,