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-editor): score the page read's AI checks: who/how/why, balance, disclosure, answer first (CE-050, part b) (#1479)

Cihan0e2ab18c608d
diff --git a/web/messages/en.json b/web/messages/en.json
index 8661b9979..81e20b4e5 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -4700,6 +4700,12 @@
"given": "It's in Your input, but the page uses none of its numbers yet",
"done": "The page uses your data"
},
+ "whoHowWhy": {
+ "title": "Say how you made this page",
+ "next": "say how you made this page",
+ "detail": "How you tested, picked or researched, and who did it (\"We hiked 120 km with each pack\"): give it in Your input, the agent writes it in as you say it",
+ "done": "The page says how it was made"
+ },
"expertQuote": {
"title": "Add an expert's quote",
"next": "add an expert's quote",
@@ -4825,6 +4831,7 @@
"reviewBrandFacts": "Review",
"keep": "Keep",
"aiCheck": "AI check",
+ "yourBrand": "your brand",
"addSource": "Add source",
"addSourceTo": "Add a source to “{claim}”",
"addProof": "Add proof link",
@@ -4847,8 +4854,8 @@
"claimNoSource": "No source for this claim. Add a source, or take it out. Content Agent will not make one up.",
"claimsPaused": "Claims in your own words wait for an AI check: this month's AI usage is used up. They're read again when it renews.",
"claimsLimited": "Today's AI checks of this page's claims are used up. Paragraphs you change now are checked when you open the page again tomorrow.",
- "pagePaused": "Claims that need your proof wait for an AI read of the page: this month's AI usage is used up. The page is read again when it renews.",
- "pageLimited": "Today's AI reads of this page are used up. Changes you make now are read when you open the page again tomorrow.",
+ "pagePaused": "The page's AI checks, and the claims that need your proof, wait for an AI read of the page: this month's AI usage is used up. The AI checks are left out of the scores until it renews.",
+ "pageLimited": "Today's AI reads of this page are used up: the page's AI checks are left out of the scores. Changes you make now are read when you open the page again tomorrow.",
"aiPaused": "Sources the rules can't place wait for an AI check: this month's AI usage is used up. They count again when it renews.",
"keepFailed": "Couldn't keep the source. Try again.",
"confirmFailed": "Couldn't save that. Try again.",
@@ -4888,6 +4895,14 @@
"line": "{kind, select, price {Price} trial {Trial length} founded {Founding year} other {A fact}} differs from brand facts · Page {page} · {source, select, pricing {pricing page} about {About page} product {product page} other {your site}} {fact}",
"detail": "{count, plural, one {Match the page to the fact you approved, or check it in Brand settings} other {# facts differ: match the page to the facts you approved, or check them in Brand settings}}"
},
+ "disclosure": {
+ "line": "The page recommends {brand} without a disclosure",
+ "detail": "Add a line saying the product the page recommends is {brand}'s own: readers and AI engines trust a page that says so."
+ },
+ "balanced": {
+ "line": "Add an honest weakness",
+ "detail": "Say where your product falls short, or where another option is the better pick: a page that only praises reads as an ad."
+ },
"avgSentence": {
"line": "Sentences average {words, number} words",
"detail": "Aim for 15–20 words: shorter sentences read faster, and AI answers quote them whole.",
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_before-publish.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_before-publish.tsx
index e0662c306..9d2db1c5d 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_before-publish.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_before-publish.tsx
@@ -122,7 +122,11 @@ export function BeforePublish({
// The biggest of what would raise Trust: the warning's reason. The claims
// a proof to-do covers count here too: the warning names them.
const [fix] = below
- ? trustSuggestions(tQuality, quality.trust)
+ ? trustSuggestions(tQuality, quality.trust, undefined, {
+ balanced: quality.aiChecks?.balanced ?? null,
+ disclosure: quality.aiChecks?.disclosure ?? null,
+ brand: quality.brandName,
+ })
.filter((s) => s.gain > 0)
.sort((a, b) => b.gain - a.gain)
: [];
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.tsx
index 7acd61f9b..52df3f7b6 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
@@ -112,7 +112,13 @@ import {
import { proofKey, qualityTodos } from '@/lib/content/quality-todos';
import { readability, sentencesOf } from '@/lib/content/readability';
import { brandFactsPath, factMismatches } from '@/lib/content/brand-facts';
-import { MAX_PROOF_TODOS, pageImages, proofsOnPage, type ProofSpot } from '@/lib/content/page-read';
+import {
+ MAX_PROOF_TODOS,
+ aiChecksOnPage,
+ pageImages,
+ proofsOnPage,
+ type ProofSpot,
+} from '@/lib/content/page-read';
import {
liveSkips,
nextStep,
@@ -358,12 +364,15 @@ export function DraftEditor({
const onDecide = useRef<(id: string, decision: SuggestionDecision) => void>(() => {});
// A picked page type, or the one the page shows as it is written. As on
// a save, a page that shows no type keeps the one it had (the stored one
- // to start with), so the header and the Library agree.
+ // to start with), so the header and the Library agree; read with the
+ // existing page's address, as Start read it, so both agree on it too.
const [picked, setPicked] = useState(draft.pageTypeSource === 'user' ? draft.pageType : null);
const [detectedType, setDetectedType] = useState(
() =>
- detectPageType({ title: draft.title, html: draft.bodyHtml }, draft.siteType) ??
- (isPageType(draft.pageType) ? draft.pageType : null),
+ detectPageType(
+ { title: draft.title, html: draft.bodyHtml, url: draft.sourceUrl },
+ draft.siteType,
+ ) ?? (isPageType(draft.pageType) ? draft.pageType : null),
);
// The brand's site type (Quality CE-056, the spec's business type), changed
// here for the whole brand; a ref too, as the editor's update handler is
@@ -372,7 +381,7 @@ export function DraftEditor({
const siteTypeRef = useRef(draft.siteType);
const detectType = (title: string, html: string) => {
const site = siteTypeRef.current;
- setDetectedType((had) => detectPageType({ title, html }, site) ?? had);
+ setDetectedType((had) => detectPageType({ title, html, url: draft.sourceUrl }, site) ?? had);
};
const pageType = picked ?? detectedType;
// The HTML view's text while it is open; null in the visual editor.
@@ -539,10 +548,6 @@ export function DraftEditor({
const language =
languageRule?.on && languageRule.current.trim() ? languageRule.current : brandLanguage;
const qualityOn = qualityPhase() >= 1;
- const readable = useMemo(
- () => (qualityOn ? readability(pageHtml, language) : null),
- [qualityOn, pageHtml, language],
- );
// Who the page is by (CE-038): page metadata, shown in the header and in a
// Page info strip outside the page; with Quality's first phase.
@@ -683,13 +688,49 @@ export function DraftEditor({
// The page's own claims that need the brand's proof (CE-049), read from
// the whole page after a save: proof to-dos while their paragraph has no
// link, and its own-site link counts as their source.
- // Only changes on their way hold the ask, as the claims': not a failed
- // save, a conflict or a page too large.
- const pageRead = usePageRead(draft.id, autosave.savedAt, sourcesOn, saving);
+ // Asked again when the page type changes too: the checks depend on it
+ // (CE-050). Only changes on their way hold the ask, as the claims': not a
+ // failed save, a conflict or a page too large.
+ const pageRead = usePageRead(
+ draft.id,
+ `${autosave.savedAt}\n${pageType ?? ''}`,
+ sourcesOn,
+ saving,
+ );
const proofAsks = useMemo(
() => (pageRead.read ? proofsOnPage(pageBlocks, pageRead.read.proofs) : []),
[pageRead.read, pageBlocks],
);
+ // The page read's AI checks (CE-050), on the page as it is: left out
+ // before the first read, and once the AI budget or the day's reads are
+ // used up (Quality says so), as the score can't follow the page then.
+ // Read for another page type: unknown until a read for this one lands.
+ // An edit holds what was found until the page as it is is read: while it
+ // waits for its save too, not only once the ask is out.
+ const pageChanging = pageRead.reading || saving;
+ const aiChecks = useMemo(
+ () =>
+ sourcesOn &&
+ pageRead.read?.checks &&
+ pageRead.read.checks.pageType === (pageType ?? null) &&
+ !pageRead.paused &&
+ !pageRead.limited
+ ? aiChecksOnPage(pageBlocks, pageRead.read.checks, pageType, pageChanging)
+ : null,
+ [
+ sourcesOn,
+ pageRead.read,
+ pageChanging,
+ pageRead.paused,
+ pageRead.limited,
+ pageBlocks,
+ pageType,
+ ],
+ );
+ const readable = useMemo(
+ () => (qualityOn ? readability(pageHtml, language, aiChecks?.answerFirst ?? null) : null),
+ [qualityOn, pageHtml, language, aiChecks],
+ );
// A proof to-do asked for this session stays, checked once it has a link.
const [hadProofs, setHadProofs] = useState<ReadonlySet<string>>(() => new Set());
// The ones shown open: the first MAX_PROOF_TODOS with no link, as the to-dos list them.
@@ -736,7 +777,13 @@ export function DraftEditor({
const eeatScore = useMemo(
() =>
qualityOn && authorsRead && !inputsPending && (!sourcesOn || visualRead)
- ? eeat({ author: pageAuthor, used, visual, confirmed: authorConfirmed })
+ ? eeat({
+ author: pageAuthor,
+ used,
+ visual,
+ how: aiChecks?.how ?? null,
+ confirmed: authorConfirmed,
+ })
: null,
[
qualityOn,
@@ -747,6 +794,7 @@ export function DraftEditor({
pageAuthor,
used,
visual,
+ aiChecks,
authorConfirmed,
],
);
@@ -795,7 +843,8 @@ export function DraftEditor({
: null,
[sourcesOn, competitorDomains, pageType, keptSources, aiKinds],
);
- // The brand's own links aren't sources: Trust waits for its domains.
+ // The brand's own links aren't sources: Trust waits for its domains. The
+ // page read's balance and disclosure (phase 2) join when it lands.
const trustScore = useMemo(
() =>
qualityOn && brandDomains && !inputsPending
@@ -809,6 +858,7 @@ export function DraftEditor({
claims: claimBlocks,
brandFacts: factCheck,
proofs: proofAsks,
+ page: aiChecks,
now: Date.now(),
})
: null,
@@ -824,6 +874,7 @@ export function DraftEditor({
claimBlocks,
factCheck,
proofAsks,
+ aiChecks,
],
);
// Their links underlined in the draft, Quality's suggestion naming them.
@@ -968,6 +1019,7 @@ export function DraftEditor({
claimsReading: claimsRead.reading,
pagePaused: pageRead.paused,
pageLimited: pageRead.limited,
+ aiChecks,
pageReading: pageRead.reading,
siteType,
brandFactsPath: sourcesOn ? brandFactsPath(draft.brandId) : null,
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx
index 3132038e9..0b810636f 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx
@@ -567,6 +567,50 @@ describe('QualityTab', () => {
);
});
+ it('asks a page that puts the brand forward to disclose it and add an honest weakness, AI checks, Show on the pick (CE-050)', async () => {
+ const PICK = 'Our top pick is the Acme Ridge 28.';
+ const result = trust({
+ blocks: trustBlocks(
+ `<p>${PICK}</p><p>Pro saves 40% of the time (<a href="https://research.example/s">study</a>).</p>`,
+ ),
+ links: new Map(),
+ brandDomains: ['acme.com'],
+ page: { balanced: { found: false }, disclosure: { found: false } },
+ now: Date.parse('2026-10-25T12:00:00Z'),
+ });
+ const pick = { found: false, show: 'Our top pick is the Acme Ridge 28' };
+ await render({
+ ...read(null),
+ brandName: 'Acme',
+ trust: result,
+ aiChecks: { balanced: pick, disclosure: pick },
+ });
+ const rows = [...container.querySelectorAll('li')];
+ const disclosure = rows.find((li) => li.textContent?.includes('Acme without a disclosure'))!;
+ expect(disclosure.textContent).toContain('The page recommends Acme without a disclosure');
+ expect(disclosure.textContent).toContain('AI check');
+ await act(async () => disclosure.querySelector('button')!.click());
+ expect(onShow).toHaveBeenCalledWith('Our top pick is the Acme Ridge 28');
+ const balance = rows.find((li) => li.textContent?.includes('Add an honest weakness'))!;
+ expect(balance.textContent).toContain('AI check');
+ // Found: nothing to raise.
+ await render({
+ ...read(null),
+ brandName: 'Acme',
+ trust: result,
+ aiChecks: { balanced: { found: true, show: null }, disclosure: { found: true, show: null } },
+ });
+ expect(container.textContent).not.toContain('Add an honest weakness');
+ // The brand's name not read yet: "your brand".
+ await render({
+ ...read(null),
+ brandName: '',
+ trust: result,
+ aiChecks: { balanced: null, disclosure: pick },
+ });
+ expect(container.textContent).toContain('The page recommends your brand without a disclosure');
+ });
+
it("asks for the proof of the page's own claims by kind and business, with Add proof link (CE-049)", async () => {
const html =
'<p>Ledgerly is 40% faster than spreadsheets.</p>' +
@@ -610,7 +654,9 @@ describe('QualityTab', () => {
// The page's other figure is still the agent's to source: one sentence, its share of the gain.
const suggestions = container.querySelector('[aria-label="What would raise it"]')!;
expect(suggestions.textContent).toContain('1 sentence with a figure has no source');
- expect(container.textContent).toContain("Today's AI reads of this page are used up.");
+ expect(container.textContent).toContain(
+ "Today's AI reads of this page are used up: the page's AI checks are left out of the scores.",
+ );
await act(async () =>
container
.querySelector<HTMLButtonElement>('[aria-label="Add a proof link to “40% faster”"]')!
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx
index 6da59f575..84fb127c8 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx
@@ -20,6 +20,7 @@ import {
type TrustRead,
} from '@/lib/content/quality-checks';
import type { QualityTodo } from '@/lib/content/quality-todos';
+import type { AiCheck } from '@/lib/content/page-read';
import {
readabilityGain,
SECTION_WORDS,
@@ -63,11 +64,16 @@ export interface QualityRead {
brandFactsPath?: string | null;
/** The brand's business type: a proof to-do's wording follows it (CE-049). */
siteType?: 'b2b' | 'ecommerce' | 'b2c';
- /** The page read for proof waits: the AI budget is spent, or its reads for the day made (CE-049). */
+ /** The page read (proof, CE-049; AI checks, CE-050) waits: the AI budget is spent, or its reads for the day made. */
pagePaused?: boolean;
pageLimited?: boolean;
- /** The page read for proof is under way: its to-dos may change. */
+ /** The page read is under way: its to-dos and AI checks may change. */
pageReading?: boolean;
+ /** The page read's AI checks, where they apply (aiChecksOnPage, CE-050). */
+ aiChecks?: {
+ balanced: AiCheck | null;
+ disclosure: AiCheck | null;
+ } | null;
/**
* With no author picked, what the person confirmed of the author their
* site names (00271): a real person, and their profile there.
@@ -155,7 +161,11 @@ export function QualityTab({
const todosLeft = todos.filter((todo) => !todo.done).length;
const suggestions = [
...readabilitySuggestions(t, readability),
- ...trustSuggestions(t, trust, proofSentences(todos)),
+ ...trustSuggestions(t, trust, proofSentences(todos), {
+ balanced: quality.aiChecks?.balanced ?? null,
+ disclosure: quality.aiChecks?.disclosure ?? null,
+ brand: quality.brandName,
+ }),
]
.filter((s) => s.gain > 0)
.sort((a, b) => b.gain - a.gain);
@@ -425,6 +435,14 @@ export function useTodoCopy() {
: t('visualProof.detail.add'),
};
}
+ // How the page was made (CE-050): the page read finds it or not.
+ if (todo.id === 'whoHowWhy') {
+ return {
+ title: t('whoHowWhy.title'),
+ next: t('whoHowWhy.next'),
+ detail: todo.done ? t('whoHowWhy.done') : t('whoHowWhy.detail'),
+ };
+ }
// What only the person can give (Brief › Your input, CE-048).
if (todo.id === 'experience' || todo.id === 'originalData' || todo.id === 'expertQuote') {
return {
@@ -648,6 +666,7 @@ function readabilitySuggestions(t: T, readability: Readability | null): Suggesti
line: line(t, check),
detail: detail(t, check),
show: check.at || null,
+ ...(check.ai ? { ai: true } : {}),
}),
);
}
@@ -668,6 +687,12 @@ export function trustSuggestions(
t: T,
trust: TrustRead | null,
covered: ReadonlySet<string> = new Set(),
+ /**
+ * Phase 2 (CE-050): the page read's balance and disclosure, each with the
+ * passage Show goes to (where the page puts the brand forward), and the
+ * brand's name for their lines.
+ */
+ page: { balanced: AiCheck | null; disclosure: AiCheck | null; brand: string } | null = null,
): TrustSuggestion[] {
if (!trust) return [];
const out: TrustSuggestion[] = [];
@@ -763,6 +788,23 @@ export function trustSuggestions(
show: null,
});
}
+ // The page read's (CE-050), once Trust is scored, as the sources' kinds.
+ for (const id of ['disclosure', 'balanced'] as const) {
+ const read = page?.[id];
+ if (!read || read.found || trust.score === null) continue;
+ out.push({
+ key: `trust:${id}`,
+ check: id,
+ score: 'trust',
+ gain: trustGain(trust, [id]),
+ // Before the brand's name is read: "your brand".
+ line: t(`checks.${id}.line`, { brand: page!.brand || t('yourBrand') }),
+ count: 1,
+ detail: t(`checks.${id}.detail`, { brand: page!.brand || t('yourBrand') }),
+ show: read.show,
+ ai: true,
+ });
+ }
if (trust.broken.length) {
out.push({
key: 'trust:noBrokenLinks',
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.tsx
index 42a804160..4d3a5af38 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
@@ -3336,6 +3336,85 @@ describe('the side panel', () => {
}
});
+ it('holds what the page read found while an edit to it is read again (review, #1479)', async () => {
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '2';
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ getContentAuthors.mockResolvedValue({
+ authors: [],
+ brands: [{ id: 'b1', name: 'Acme' }],
+ me: { id: 'u1', role: 'admin' },
+ });
+ const HOW = 'We tested each forecasting app with twelve sales teams for a month.';
+ const answer = (block: string) => ({
+ spots: [],
+ proofs: [],
+ regulated: null,
+ checks: {
+ answerFirst: null,
+ recommends: null,
+ disclosure: null,
+ balance: null,
+ how: { quote: 'We tested each forecasting app', block },
+ cut: false,
+ pageType: 'guide',
+ },
+ pending: false,
+ limited: false,
+ paused: false,
+ });
+ let again: (value: unknown) => void = () => {};
+ readDraftPage
+ .mockResolvedValueOnce(answer(HOW))
+ .mockReturnValueOnce(new Promise((resolve) => (again = resolve)));
+ saveContentDraft.mockResolvedValue({
+ ok: true,
+ updatedAt: '2026-10-20T10:01:00Z',
+ bodyHash: 'h1',
+ });
+ getContentDraft.mockResolvedValue({
+ ...claimed,
+ pageType: 'guide',
+ pageTypeSource: 'user',
+ bodyHtml: `${claimed.bodyHtml}<p>${HOW}</p>`,
+ });
+ window.innerWidth = 1440;
+ await renderPage();
+ await act(async () => void (await vi.advanceTimersByTimeAsync(3_000)));
+ const chip = [...container.querySelectorAll<HTMLButtonElement>('header button')].find((b) =>
+ b.textContent?.startsWith('Quality'),
+ )!;
+ await act(async () => chip.click());
+ const eeatNow = () => panel()!.textContent!.match(/E-E-A-T(\d+)/)?.[1];
+ const found = eeatNow();
+ expect(found).toBeDefined();
+ // A typo fixed in the paragraph that says how the page was made.
+ const editor = (container.querySelector('.ProseMirror') as HTMLElement & { editor: Editor })
+ .editor;
+ let end = -1;
+ editor.state.doc.descendants((node, pos) => {
+ if (node.isTextblock && node.textContent === HOW) end = pos + node.nodeSize - 1;
+ });
+ await act(async () => {
+ editor.commands.insertContentAt(end - 1, ' straight');
+ });
+ // Read on the page as it is now, not saved yet; then saved and not
+ // asked about; then asked: it holds.
+ await act(async () => void (await vi.advanceTimersByTimeAsync(500)));
+ expect(saveContentDraft).not.toHaveBeenCalled();
+ expect(eeatNow()).toBe(found);
+ await act(async () => void (await vi.advanceTimersByTimeAsync(1_500)));
+ expect(saveContentDraft).toHaveBeenCalled();
+ expect(eeatNow()).toBe(found);
+ await act(
+ async () =>
+ void (await vi.advanceTimersByTimeAsync(PROOF_READ_EVERY_MS + PROOF_READ_SLACK_MS)),
+ );
+ expect(readDraftPage).toHaveBeenCalledTimes(2);
+ expect(eeatNow()).toBe(found);
+ await act(async () => again(answer(HOW.replace('month.', 'month straight.'))));
+ expect(eeatNow()).toBe(found);
+ });
+
it('takes the claim’s sentence out on Remove', async () => {
process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '2';
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
diff --git a/web/src/lib/actions/content-drafts-page-read.test.ts b/web/src/lib/actions/content-drafts-page-read.test.ts
new file mode 100644
index 000000000..7cd27ce32
--- /dev/null
+++ b/web/src/lib/actions/content-drafts-page-read.test.ts
@@ -0,0 +1,76 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/** The page read (CE-049) and its AI checks (CE-050), as the API gives them. */
+
+const DRAFT = '77777777-7777-7777-7777-777777777777';
+
+vi.mock('@/lib/action-center/assignees', () => ({ readAssignees: vi.fn(async () => new Map()) }));
+vi.mock('@/lib/supabase/admin', () => ({ supabaseAdmin: {} }));
+vi.mock('@/lib/supabase/server', () => ({
+ createClient: vi.fn(async () => ({
+ auth: { getSession: async () => ({ data: { session: { access_token: 't' } } }) },
+ })),
+}));
+
+const { readDraftPage } = await import('./content-drafts');
+
+const answer = (body: unknown, status = 200) =>
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => new Response(JSON.stringify(body), { status })),
+ );
+
+const PICK = {
+ quote: 'Our top pick is Ridge 28',
+ block: 'Our top pick is Ridge 28, ahead of Talon.',
+};
+
+beforeEach(() => answer({ spots: [], proofs: [], regulated: null, checks: null }));
+afterEach(() => vi.unstubAllGlobals());
+
+describe('readDraftPage', () => {
+ it('gives the checks the page read found, each with its words', async () => {
+ answer({
+ spots: [],
+ proofs: [],
+ regulated: null,
+ checks: {
+ answerFirst: { answers: false, block: 'By the way, packs vary.' },
+ recommends: PICK,
+ disclosure: null,
+ balance: { quote: '', block: 'x' },
+ how: { block: 'no quote' },
+ cut: true,
+ pageType: 'best_of',
+ },
+ pending: false,
+ });
+ expect(await readDraftPage(DRAFT)).toMatchObject({
+ checks: {
+ answerFirst: { answers: false, block: 'By the way, packs vary.' },
+ recommends: PICK,
+ disclosure: null,
+ // Not a find: no words, or no quote.
+ balance: null,
+ how: null,
+ cut: true,
+ pageType: 'best_of',
+ },
+ });
+ });
+
+ it('gives no checks for a read without them, or one shaped otherwise', async () => {
+ expect(await readDraftPage(DRAFT)).toMatchObject({ checks: null });
+ answer({ spots: [], proofs: [], regulated: null, checks: 'yes' });
+ expect(await readDraftPage(DRAFT)).toMatchObject({ checks: null });
+ answer({
+ spots: [],
+ proofs: [],
+ regulated: null,
+ checks: { answerFirst: { answers: 'yes', block: 'x' } },
+ });
+ expect(await readDraftPage(DRAFT)).toMatchObject({
+ checks: { answerFirst: null, recommends: null, cut: false, pageType: null },
+ });
+ });
+});
diff --git a/web/src/lib/actions/content-drafts.test.ts b/web/src/lib/actions/content-drafts.test.ts
index 79131c063..625895458 100644
--- a/web/src/lib/actions/content-drafts.test.ts
+++ b/web/src/lib/actions/content-drafts.test.ts
@@ -316,6 +316,23 @@ describe('the page type on save (CE-023)', () => {
});
expect(calls.map((call) => call.op)).toEqual(['update', 'update']);
});
+
+ it('reads it with the existing page’s address, as Start did (review, #1479)', async () => {
+ updated = {
+ updated_at: '2026-10-20T15:00:00Z',
+ page_type: 'blog_post',
+ page_type_source: 'detected',
+ source_url: 'https://shop.example/blog/ultralight-tents-for-wet-trips',
+ brands: shop,
+ };
+ // A best-of title on a /blog/ page: still the blog post Start read it as.
+ await saveContentDraft(DRAFT, {
+ title: 'The 7 best ultralight tents',
+ bodyHtml: '<h1>The 7 best ultralight tents</h1>',
+ base,
+ });
+ expect(calls.map((call) => call.op)).toEqual(['update']);
+ });
});
describe('setContentDraftPageType', () => {
diff --git a/web/src/lib/actions/content-drafts.ts b/web/src/lib/actions/content-drafts.ts
index de688ced1..fa3cd051b 100644
--- a/web/src/lib/actions/content-drafts.ts
+++ b/web/src/lib/actions/content-drafts.ts
@@ -39,7 +39,12 @@ import { sanitizeDraftHtml } from '@/lib/content/sanitize-draft-html';
import { matchPagePrompts } from '@/lib/content/page-prompts';
import type { LinkCheck } from '@/lib/content/quality-checks';
import { CLAIM_KINDS, type ClaimBlock } from '@/lib/content/claims';
-import { PROOF_KINDS, type PageRead } from '@/lib/content/page-read';
+import {
+ PROOF_KINDS,
+ type PageChecks,
+ type PageQuote,
+ type PageRead,
+} from '@/lib/content/page-read';
import { MAX_SOURCE_SITES, type AiSourceClass } from '@/lib/content/source-class';
import {
NO_DRAFT_RULES,
@@ -1268,13 +1273,17 @@ export async function saveContentDraft(
.eq('id', id)
.eq('updated_at', expected)
.or(`agent_state.is.null,agent_state.neq.writing,agent_state_at.lt."${writingSince}"`)
- .select(`updated_at, page_type, page_type_source, ${BRAND_SITE}`)
+ .select(`updated_at, page_type, page_type_source, source_url, ${BRAND_SITE}`)
.maybeSingle();
if (error) throw new Error(error.message);
if (data) {
let updatedAt: string = data.updated_at;
if (data.page_type_source === 'detected') {
- const detected = detectPageType({ title, html: bodyHtml }, brandSiteType(data.brands));
+ // With the existing page's address, as Start detected it.
+ const detected = detectPageType(
+ { title, html: bodyHtml, url: data.source_url },
+ brandSiteType(data.brands),
+ );
// A page that shows no type keeps the one it had (Start's guess).
if (detected && detected !== data.page_type) {
// Only over this save: a write in between would otherwise become
@@ -1720,14 +1729,14 @@ export async function restoreDraftVersion(id: string, versionId: string): Promis
// Read back, so the type is detected only on the draft the version restored.
const { data: row, error: rowError } = await supabase
.from('content_drafts')
- .select(`page_type, page_type_source, body_html, ${BRAND_SITE}`)
+ .select(`page_type, page_type_source, body_html, source_url, ${BRAND_SITE}`)
.eq('id', id)
.maybeSingle();
if (rowError) {
console.error('Failed to read the restored draft:', rowError.message);
} else if (row?.page_type_source === 'detected' && row.body_html === restored.bodyHtml) {
const detected = detectPageType(
- { title: restored.title, html: restored.bodyHtml },
+ { title: restored.title, html: restored.bodyHtml, url: row.source_url },
brandSiteType(row.brands),
);
// A page that shows no type keeps the one it had, as on a save.
@@ -2372,6 +2381,32 @@ export async function saveMyRuleSet(
if (error) throw new Error(error.message);
}
+/** The page read's checks as the API gives them (CE-050), each found one with its words; else null. */
+function pageChecksOf(value: unknown): PageChecks | null {
+ if (!value || typeof value !== 'object') return null;
+ const checks = value as Record<string, unknown>;
+ const text = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+ const quote = (v: unknown): PageQuote | null => {
+ const find = v as Partial<PageQuote> | null;
+ return find && text(find.quote) && text(find.block)
+ ? { quote: find.quote, block: find.block }
+ : null;
+ };
+ const first = checks.answerFirst as { answers?: unknown; block?: unknown } | null;
+ return {
+ answerFirst:
+ first && typeof first.answers === 'boolean' && text(first.block)
+ ? { answers: first.answers, block: first.block }
+ : null,
+ recommends: quote(checks.recommends),
+ disclosure: quote(checks.disclosure),
+ balance: quote(checks.balance),
+ how: quote(checks.how),
+ cut: checks.cut === true,
+ pageType: typeof checks.pageType === 'string' ? checks.pageType : null,
+ };
+}
+
/**
* Quality's page read for proof (CE-049): the draft's visual proof spots
* and proof asks, read by the API from the page as saved, with its page
@@ -2406,7 +2441,8 @@ export async function readDraftPage(
return { error: body.code === 'off' ? 'off' : 'failed' };
}
if (!res.ok) return { error: 'failed' };
- const body = (await res.json()) as Partial<PageRead> & {
+ const body = (await res.json()) as Partial<Omit<PageRead, 'checks'>> & {
+ checks?: unknown;
pending?: boolean;
limited?: boolean;
paused?: boolean;
@@ -2424,6 +2460,7 @@ export async function readDraftPage(
body.regulated === 'health' || body.regulated === 'finance' || body.regulated === 'legal'
? body.regulated
: null,
+ checks: pageChecksOf(body.checks),
pending: body.pending ?? false,
limited: body.limited ?? false,
paused: body.paused ?? false,
diff --git a/web/src/lib/content/page-read.test.ts b/web/src/lib/content/page-read.test.ts
index d7ecb25f1..7c3a831fa 100644
--- a/web/src/lib/content/page-read.test.ts
+++ b/web/src/lib/content/page-read.test.ts
@@ -1,5 +1,11 @@
import { describe, expect, it } from 'vitest';
-import { pageImages, proofsOnPage, type ProofAsk } from './page-read';
+import {
+ aiChecksOnPage,
+ pageImages,
+ proofsOnPage,
+ type PageChecks,
+ type ProofAsk,
+} from './page-read';
import { trustBlocks } from './quality-checks';
/** The page read's proof asks on the page as it is now (Quality spec §4b, CE-049). */
@@ -94,3 +100,85 @@ describe('pageImages', () => {
]);
});
});
+
+describe('aiChecksOnPage (CE-050)', () => {
+ const PICK = 'Our top pick is the Trailmade Ridge 28, ahead of the Osprey Talon.';
+ const HOW = 'We hiked 120 km in the rain with each pack.';
+ const FIRST = 'The best daypack for wet hikes is the Trailmade Ridge 28.';
+ const blocks = trustBlocks(`<h1>Best daypacks</h1><p>${FIRST}</p><p>${PICK}</p><p>${HOW}</p>`);
+ const checks = (over: Partial<PageChecks> = {}): PageChecks => ({
+ answerFirst: { answers: true, block: FIRST },
+ recommends: { quote: 'Our top pick is the Trailmade Ridge 28', block: PICK },
+ disclosure: null,
+ balance: null,
+ how: { quote: 'We hiked 120 km', block: HOW },
+ cut: false,
+ pageType: 'best_of',
+ ...over,
+ });
+
+ it('asks a page that puts the brand forward for its disclosure and its balance, Show on the pick', () => {
+ expect(aiChecksOnPage(blocks, checks(), 'best_of')).toEqual({
+ how: { found: true, show: 'We hiked 120 km' },
+ balanced: { found: false, show: 'Our top pick is the Trailmade Ridge 28' },
+ disclosure: { found: false, show: 'Our top pick is the Trailmade Ridge 28' },
+ answerFirst: { answers: true, block: FIRST },
+ });
+ });
+
+ it('counts each check only where it applies', () => {
+ // A feature page puts nothing forward and says nothing of how it was made.
+ expect(aiChecksOnPage(blocks, checks({ recommends: null }), 'feature_page')).toMatchObject({
+ how: null,
+ balanced: null,
+ disclosure: null,
+ });
+ // A comparison weighs options: its balance counts without the brand put forward.
+ expect(aiChecksOnPage(blocks, checks({ recommends: null }), 'comparison')).toMatchObject({
+ balanced: { found: false, show: null },
+ disclosure: null,
+ });
+ });
+
+ it('counts a find whose block is gone as not found, and leaves one out on a page read in part', () => {
+ const edited = trustBlocks(`<h1>Best daypacks</h1><p>${PICK}</p><p>We tested them.</p>`);
+ expect(aiChecksOnPage(edited, checks(), 'best_of')).toMatchObject({
+ how: { found: false },
+ answerFirst: null,
+ });
+ // Cut: one not found may be in the rest; one found still counts.
+ expect(aiChecksOnPage(edited, checks({ cut: true }), 'best_of')).toMatchObject({
+ how: null,
+ disclosure: null,
+ });
+ expect(aiChecksOnPage(blocks, checks({ cut: true }), 'best_of').how).toEqual({
+ found: true,
+ show: 'We hiked 120 km',
+ });
+ // While the page as it is now is read, a find whose block was edited still counts.
+ expect(aiChecksOnPage(edited, checks(), 'best_of', true).how).toEqual({
+ found: true,
+ show: null,
+ });
+ });
+
+ it('holds the pick and Answer first’s verdict while the edited page is read again (review, #1479)', () => {
+ const typo = trustBlocks(
+ `<h1>Best daypacks</h1><p>The best daypack for wet hikes is the Trailmade Ridge 28!</p><p>Our top pick is the Trailmade Ridge 28, ahead of the Osprey Talon!</p><p>${HOW}</p>`,
+ );
+ // Read again: the pick still applies (no Show: its words moved), the verdict is held.
+ expect(aiChecksOnPage(typo, checks(), 'feature_page', true)).toEqual({
+ how: null,
+ balanced: { found: false, show: null },
+ disclosure: { found: false, show: null },
+ answerFirst: { answers: true, block: FIRST, held: true },
+ });
+ // Once read and still edited: the pick doesn't apply, and the verdict goes.
+ expect(aiChecksOnPage(typo, checks(), 'feature_page')).toEqual({
+ how: null,
+ balanced: null,
+ disclosure: null,
+ answerFirst: null,
+ });
+ });
+});
diff --git a/web/src/lib/content/page-read.ts b/web/src/lib/content/page-read.ts
index c8e482f32..ac0ce504f 100644
--- a/web/src/lib/content/page-read.ts
+++ b/web/src/lib/content/page-read.ts
@@ -46,6 +46,116 @@ export interface PageRead {
spots: ProofSpot[];
proofs: ProofAsk[];
regulated: 'health' | 'finance' | 'legal' | null;
+ /** The page's AI checks (CE-050); null when the page wasn't read for them. */
+ checks: PageChecks | null;
+}
+
+/** A check's find (CE-050): its words and its block's, as the page has them. */
+export interface PageQuote {
+ quote: string;
+ block: string;
+}
+
+/**
+ * What the page read says of the page (CE-050), each found one in its
+ * block's own words: whether the paragraph after the H1 answers it; where
+ * the page puts the brand forward among options; a line saying the brand
+ * makes what it recommends; a real limit of the brand's own product, or
+ * where another option wins; how the page's content was made.
+ */
+export interface PageChecks {
+ answerFirst: { answers: boolean; block: string } | null;
+ recommends: PageQuote | null;
+ disclosure: PageQuote | null;
+ balance: PageQuote | null;
+ how: PageQuote | null;
+ /** The model read less than the whole page: one not found may be in the rest. */
+ cut: boolean;
+ /** The page type they were read for: for another one, they're unknown until it's read. */
+ pageType: string | null;
+}
+
+/** Pages a reader trusts more for saying how they were made: tested, picked, researched. */
+export const HOW_TYPES: ReadonlySet<string> = new Set([
+ 'best_of',
+ 'comparison',
+ 'alternatives',
+ 'buying_guide',
+ 'guide',
+ 'blog_post',
+]);
+/** Pages that weigh options: the brand's own limits belong on them. */
+export const WEIGHING_TYPES: ReadonlySet<string> = new Set([
+ 'comparison',
+ 'alternatives',
+ 'best_of',
+ 'buying_guide',
+]);
+
+/** One AI check on the page as it is: found, and the passage Show goes to. */
+export interface AiCheck {
+ found: boolean;
+ show: string | null;
+}
+
+/**
+ * The page's AI checks as they count (CE-050), on the page as it is now (a
+ * find whose block is gone counts as not found, until the next read):
+ *
+ * * how (E-E-A-T's who / how / why): on pages a reader trusts more for
+ * saying how they were made (HOW_TYPES);
+ * * balanced (Trust): on pages that weigh options (WEIGHING_TYPES), or
+ * where the page puts the brand forward; Show goes to that passage;
+ * * disclosure (Trust): only where the page puts the brand forward;
+ * * answerFirst (Readability): the model's verdict on the paragraph
+ * after the H1, while it is still there.
+ *
+ * Each is null where it doesn't apply, and one not found is left out on a
+ * page the model read only part of (`cut`): it may be in the rest. Until
+ * the page as it is now is read (`reading`: changes not saved yet, a save
+ * not asked about, an ask out), a find whose block changed counts as still
+ * found, the passage that puts the brand forward still applies and Answer
+ * first's verdict holds (`held`): a small edit doesn't move the scores.
+ */
+export function aiChecksOnPage(
+ blocks: TrustBlock[],
+ checks: PageChecks,
+ pageType: string | null,
+ reading = false,
+): {
+ how: AiCheck | null;
+ balanced: AiCheck | null;
+ disclosure: AiCheck | null;
+ answerFirst: { answers: boolean; block: string; held?: boolean } | null;
+} {
+ const words = new Set(blocks.map((b) => squeeze(b.text)));
+ const here = (find: PageQuote | null) =>
+ find && words.has(squeeze(find.block)) && squeeze(find.block).includes(squeeze(find.quote))
+ ? find
+ : null;
+ const recommendsHere = here(checks.recommends);
+ const recommends = recommendsHere ?? (reading ? checks.recommends : null);
+ const check = (find: PageQuote | null, show: string | null): AiCheck | null => {
+ const found = here(find);
+ if (!found && find && reading) return { found: true, show: null };
+ if (!found && checks.cut) return null;
+ return { found: !!found, show: found ? found.quote : show };
+ };
+ return {
+ how: pageType && HOW_TYPES.has(pageType) ? check(checks.how, null) : null,
+ balanced:
+ recommends || (pageType && WEIGHING_TYPES.has(pageType))
+ ? check(checks.balance, recommendsHere?.quote ?? null)
+ : null,
+ disclosure: recommends ? check(checks.disclosure, recommendsHere?.quote ?? null) : null,
+ answerFirst: !checks.answerFirst
+ ? null
+ : words.has(squeeze(checks.answerFirst.block))
+ ? checks.answerFirst
+ : reading
+ ? { ...checks.answerFirst, held: true }
+ : null,
+ };
}
/** The proof to-dos open at once at most: the page's first claims. */
diff --git a/web/src/lib/content/quality-checks.test.ts b/web/src/lib/content/quality-checks.test.ts
index c33fda26d..578278998 100644
--- a/web/src/lib/content/quality-checks.test.ts
+++ b/web/src/lib/content/quality-checks.test.ts
@@ -656,3 +656,38 @@ describe('trust: the proof of the brand’s own claims (Phase 2, CE-049)', () =>
expect(sentenceGain(null, sentence)).toBe(0);
});
});
+
+describe('the page read’s AI checks (Phase 2, CE-050)', () => {
+ const NOW = Date.parse('2026-10-25T12:00:00Z');
+ it('counts who / how / why in E-E-A-T where it applies', () => {
+ expect(eeat({ author: null, how: { found: true } }).checks).toContainEqual({
+ id: 'whoHowWhy',
+ points: 10,
+ max: 10,
+ });
+ expect(eeat({ author: null, how: { found: false } }).checks).toContainEqual({
+ id: 'whoHowWhy',
+ points: 0,
+ max: 10,
+ });
+ expect(eeat({ author: null }).checks.map((c) => c.id)).not.toContain('whoHowWhy');
+ });
+
+ it('counts balance and disclosure in Trust where they apply, and scores no Trust from them alone', () => {
+ const read = (
+ page: Parameters<typeof trust>[0]['page'],
+ html = '<p>Pro saves 40% of the time (<a href="https://research.example/study">study</a>).</p>',
+ ) => trust({ blocks: trustBlocks(html), links: new Map(), brandDomains: [], page, now: NOW });
+ const both = read({ balanced: { found: false }, disclosure: { found: true } });
+ expect(both.checks.filter((c) => c.id === 'balanced' || c.id === 'disclosure')).toEqual([
+ { id: 'balanced', points: 0, max: 7 },
+ { id: 'disclosure', points: 5, max: 5 },
+ ]);
+ expect(read({ balanced: null, disclosure: null }).checks.map((c) => c.id)).toEqual([
+ 'claimsSourced',
+ ]);
+ expect(
+ read({ balanced: { found: true }, disclosure: null }, '<p>No figure here.</p>').score,
+ ).toBeNull();
+ });
+});
diff --git a/web/src/lib/content/quality-checks.ts b/web/src/lib/content/quality-checks.ts
index 2717e4634..364458095 100644
--- a/web/src/lib/content/quality-checks.ts
+++ b/web/src/lib/content/quality-checks.ts
@@ -147,9 +147,16 @@ export function eeat({
author,
used = null,
visual = null,
+ how = null,
confirmed = null,
}: {
author: ContentAuthor | null;
+ /**
+ * Phase 2 (CE-050): whether the page says how it was made (tested,
+ * picked, researched, by whom), as the page read finds it; null where it
+ * doesn't apply or isn't read.
+ */
+ how?: { found: boolean } | null;
/**
* Phase 2 (CE-049): the page's images, how many of them the person
* confirmed are their own (not stock), and the visual proof spots still
@@ -195,6 +202,15 @@ export function eeat({
},
]
: []),
+ ...(how
+ ? [
+ {
+ id: 'whoHowWhy' as const,
+ points: how.found ? EEAT_WEIGHTS.whoHowWhy : 0,
+ max: EEAT_WEIGHTS.whoHowWhy,
+ },
+ ]
+ : []),
{
id: 'byline',
points: author || confirmed?.real ? EEAT_WEIGHTS.byline : 0,
@@ -394,6 +410,11 @@ export interface SourceRead {
* claim (an award, a certification, its own test) is sourced by a link in
* its block to the brand's own site too: its award or trust page is the
* proof. The block's other sentences aren't.
+ *
+ * With `page` (Phase 2, CE-050), the page read's balance (the brand's own
+ * limits, or where another option wins) and disclosure (where the page puts
+ * the brand forward) count where they apply. Like the brand's facts, they
+ * don't score Trust on their own.
*/
export function trust({
blocks,
@@ -405,6 +426,7 @@ export function trust({
claims = null,
brandFacts = null,
proofs = null,
+ page = null,
now,
}: {
/** The page's blocks (trustBlocks). */
@@ -430,6 +452,8 @@ export function trust({
* read's proofs on the page, CE-049).
*/
proofs?: readonly { block: string; sentence: string }[] | null;
+ /** Phase 2: the page read's balance and disclosure, each null where it doesn't apply (CE-050). */
+ page?: { balanced: { found: boolean } | null; disclosure: { found: boolean } | null } | null;
now: number;
}): TrustRead {
const all = pageLinks(blocks, brandDomains);
@@ -576,6 +600,12 @@ export function trust({
});
}
+ for (const id of ['balanced', 'disclosure'] as const) {
+ const found = page?.[id];
+ if (found)
+ checks.push({ id, points: found.found ? TRUST_WEIGHTS[id] : 0, max: TRUST_WEIGHTS[id] });
+ }
+
if (quote !== null) {
checks.push({
id: 'expertQuote',
diff --git a/web/src/lib/content/quality-todos.test.ts b/web/src/lib/content/quality-todos.test.ts
index a35b9af54..73669ecd5 100644
--- a/web/src/lib/content/quality-todos.test.ts
+++ b/web/src/lib/content/quality-todos.test.ts
@@ -389,6 +389,20 @@ describe('qualityTodos', () => {
).toMatchObject([{ id: 'proof', done: true }]);
});
+ it('asks how the page was made where the page read counts it (CE-050)', () => {
+ const how = (found: boolean | null) =>
+ qualityTodos({
+ eeat: eeat({ author: author(), how: found === null ? null : { found } }),
+ author: author(),
+ hasAuthors: true,
+ used: { experience: false, data: false, quote: false },
+ }).find((t) => t.id === 'whoHowWhy');
+ expect(how(false)).toMatchObject({ done: false, action: 'addInput', score: 'eeat' });
+ expect(how(false)!.gain).toBeGreaterThan(0);
+ expect(how(true)).toMatchObject({ done: true, gain: 0 });
+ expect(how(null)).toBeUndefined();
+ });
+
it('offers to confirm the author the site names instead of picking one, the profile once they are', () => {
const read = (real: boolean, profile: boolean) =>
qualityTodos({
diff --git a/web/src/lib/content/quality-todos.ts b/web/src/lib/content/quality-todos.ts
index af900e3c5..199d1e46e 100644
--- a/web/src/lib/content/quality-todos.ts
+++ b/web/src/lib/content/quality-todos.ts
@@ -29,6 +29,7 @@ export type QualityTodoId =
| 'experience'
| 'originalData'
| 'visualProof'
+ | 'whoHowWhy'
| 'expertQuote'
| 'proof'
| 'reviewer'
@@ -247,8 +248,10 @@ export function qualityTodos({
},
] satisfies QualityTodo[])
: []),
- // Not Your input's: listed in its place when that can't be read too.
+ // Not Your input's (read from the page): listed in their place when
+ // that can't be read too.
...visualTodo(eeat, visual),
+ ...howTodo(eeat),
...(used
? ([
{
@@ -287,6 +290,26 @@ function shortHash(text: string): string {
export const proofKey = (ask: { claim: string; block: string }) =>
`proof:${squeeze(ask.claim)}:${shortHash(squeeze(ask.block))}`;
+/**
+ * Who / how / why (CE-050): the page says how it was made (how it was
+ * tested, how the picks were chosen, by whom). Only the person knows: Brief
+ * › Your input. Listed where the check counts (the page read's, on pages a
+ * reader trusts more for it).
+ */
+function howTodo(eeat: Score<EeatCheckId>): QualityTodo[] {
+ const check = eeat.checks.find((c) => c.id === 'whoHowWhy');
+ if (!check) return [];
+ return [
+ {
+ id: 'whoHowWhy',
+ done: check.points >= check.max,
+ gain: scoreGain(eeat, ['whoHowWhy']),
+ score: 'eeat',
+ action: 'addInput',
+ },
+ ];
+}
+
/**
* Visual proof (CE-049): an image the person took themself. Images on the
* page none of them confirmed: Confirm (only the person can tell their own
diff --git a/web/src/lib/content/readability.test.ts b/web/src/lib/content/readability.test.ts
index dcc595e74..9c8162ec1 100644
--- a/web/src/lib/content/readability.test.ts
+++ b/web/src/lib/content/readability.test.ts
@@ -261,6 +261,44 @@ describe('reading the page as written', () => {
// A short H1 is read by all its words.
const short = `<h1>What is AI?</h1>${p('AI is software that answers questions.')}${body}`;
expect(check(short, 'answerFirst')!.points).toBe(15);
+ // A byline or a date under the H1 is read past: the answer is the paragraph after it.
+ const bylined = `<h1>Pipeline forecasting</h1>${p('By Jane Doe · October 2026')}${p('Pipeline forecasting is how a team guesses what will close.')}${body}`;
+ expect(check(bylined, 'answerFirst')!.points).toBe(15);
+ // A dated byline's numbers aren't words, as the API counts them.
+ const dated = `<h1>Pipeline forecasting</h1>${p('By Jane Doe · Updated Oct 25, 2026 · 6 min read')}${p('Pipeline forecasting is how a team guesses what will close.')}${body}`;
+ expect(check(dated, 'answerFirst')!.points).toBe(15);
+ });
+
+ it('takes the model’s verdict on the first paragraph in phase 2, while it is still first (CE-050)', () => {
+ const body = p(Array.from({ length: 4 }, () => sentence(15)).join(' '));
+ const first = 'Pipeline forecasting is how a small team guesses what will close.';
+ const html = `<h1>Pipeline forecasting for small teams</h1>${p(first)}${body}`;
+ const read = (aiAnswer: { answers: boolean; block: string; held?: boolean } | null) =>
+ readability(html, 'en', aiAnswer).checks.find((c) => c.id === 'answerFirst')!;
+ // The rule passes it; the model says it doesn't answer.
+ expect(read(null)).toMatchObject({ points: 15 });
+ expect(read(null).ai).toBeUndefined();
+ expect(read({ answers: false, block: first })).toMatchObject({
+ points: 0,
+ ai: true,
+ at: first,
+ });
+ // A verdict on another paragraph (the page changed since): the rule reads it.
+ expect(read({ answers: false, block: 'Teams like a calm Monday.' })).toMatchObject({
+ points: 15,
+ });
+ // Held while the edited page is read again: the verdict stays (review, #1479).
+ expect(
+ read({ answers: false, block: 'Pipeline forecasting is how teams guess.', held: true }),
+ ).toMatchObject({ points: 0, ai: true });
+ // It answers, but it's still a short paragraph to pass.
+ const long = `Pipeline ${sentence(70)}`;
+ expect(
+ readability(`<h1>Pipeline forecasting</h1>${p(long)}${body}`, 'en', {
+ answers: true,
+ block: long,
+ }).checks.find((c) => c.id === 'answerFirst'),
+ ).toMatchObject({ points: 0, ai: true });
});
it('keeps an abbreviation inside its sentence, and reads passive voice and jargon closely', () => {
diff --git a/web/src/lib/content/readability.ts b/web/src/lib/content/readability.ts
index b0666a02b..24ed3779c 100644
--- a/web/src/lib/content/readability.ts
+++ b/web/src/lib/content/readability.ts
@@ -40,6 +40,20 @@ export const PARAGRAPH_SENTENCES = 4;
export const SECTION_WORDS = 300;
/** A page shorter than this gets no Readability score yet: too little to read. */
export const MIN_WORDS = 50;
+/**
+ * A paragraph under the H1 this short and not a sentence (no full stop at
+ * its end) is a byline, a date or a note: answer first reads past it.
+ */
+export const MIN_ANSWER_WORDS = 8;
+const ENDS_A_SENTENCE = /[.!?…。!?]["”’')\]]*$/u;
+/**
+ * A byline, a date or a note: short, and not a sentence ("By Jane Doe ·
+ * October 2026"), its words counted as the API's page read counts them
+ * (a number isn't one), so both read the same first paragraph.
+ */
+export const isByline = (text: string) =>
+ (text.match(/\p{L}[\p{L}\p{N}'’-]*/gu) ?? []).length < MIN_ANSWER_WORDS &&
+ !ENDS_A_SENTENCE.test(text.trim());
export type ReadingFormula = 'flesch' | 'atesman' | 'amstad' | 'kandelMoles' | 'fernandezHuerta';
@@ -57,6 +71,8 @@ export interface ReadabilityCheck {
target?: number;
/** English's band instead of a target: the score that reads right for most readers. */
band?: { min: number; max: number };
+ /** Read by the model, not by rules: its suggestion says so ("AI check", CE-050). */
+ ai?: boolean;
/** The first block that falls short, to show it in the draft. */
at?: string | null;
}
@@ -371,7 +387,16 @@ const COMMON = new Set([
* be read. `language` is the one the draft is written in (its Language rule,
* else the brand's), English when unset.
*/
-export function readability(html: string, language: string | null | undefined): Readability {
+export function readability(
+ html: string,
+ language: string | null | undefined,
+ /**
+ * Phase 2 (CE-050): the model's verdict on the paragraph after the H1,
+ * with that paragraph's words; it stands while the paragraph is still
+ * the first, else the rule reads it.
+ */
+ aiAnswer: { answers: boolean; block: string; held?: boolean } | null = null,
+): Readability {
const blocks = readBlocks(html);
const lang = languageCode(language);
const prose = blocks.filter(isProse);
@@ -450,11 +475,16 @@ export function readability(html: string, language: string | null | undefined):
});
}
- // Answer first: the first block under the H1 is a short paragraph that
- // names what the H1 asks (a heuristic; Phase 2 reads it with a model). A
- // page without an H1 has nothing to answer, and doesn't pass.
+ // Answer first: the first block under the H1 (past a byline, a date or a
+ // note) is a short paragraph that names what the H1 asks (a heuristic;
+ // Phase 2 reads it with a model, as the API's page read finds the same
+ // paragraph). A page without an H1 has nothing to answer, and doesn't pass.
const h1 = blocks.findIndex((b) => b.tag === 'h1');
- const first = h1 === -1 ? undefined : blocks[h1 + 1];
+ let at = h1 === -1 ? -1 : h1 + 1;
+ while (at !== -1 && blocks[at]?.tag === 'p' && isByline(blocks[at].text)) {
+ at += 1;
+ }
+ const first = at === -1 ? undefined : blocks[at];
const wordsOf = (text: string) => text.toLocaleLowerCase(lang ?? 'en').match(/\p{L}{2,}/gu) ?? [];
// The H1's subject: its words but the question words and the commonest
// ones, the longer ones when it has any ("What is AI?" is about "ai").
@@ -462,17 +492,25 @@ export function readability(html: string, language: string | null | undefined):
const subject = new Set(
h1Words.some((w) => w.length >= 4) ? h1Words.filter((w) => w.length >= 4) : h1Words,
);
- const answers =
+ const read =
!!first &&
- first.tag === 'p' &&
- first.words <= 60 &&
- wordsOf(first.text).some((w) => subject.has(w));
+ !!aiAnswer &&
+ // Held while the edited page is read again (aiChecksOnPage).
+ (!!aiAnswer.held || first.text.replace(/\s+/g, '') === aiAnswer.block.replace(/\s+/g, ''));
+ // The model reads whether it answers; it is still a short paragraph to pass.
+ const answers = read
+ ? aiAnswer!.answers && first.words <= 60
+ : !!first &&
+ first.tag === 'p' &&
+ first.words <= 60 &&
+ wordsOf(first.text).some((w) => subject.has(w));
check({
id: 'answerFirst',
points: answers ? READABILITY_WEIGHTS.answerFirst : 0,
value: first?.words ?? 0,
count: answers ? 0 : 1,
at: answers ? null : (first?.text ?? (h1 === -1 ? null : blocks[h1].text)),
+ ...(read ? { ai: true } : {}),
});
// Short paragraphs: the share with at most 4 sentences.