All documentation

Optimize

Articles

How a topic becomes a brief, a draft with its claims checked against the sources it names, and a published page tied back to the gap it closes.

Articles screen showing this week's best opportunity from a citation gap, drafts ready to publish, and articles in progress

What this is for

Citation gaps finds the prompts where a competitor is cited and you are not. Articles is where you decide what to do about it: not "write a blog post," but which page should actually exist to win that prompt. On plans that draft it grounded in evidence, that means building from the sources already winning it today. A topic starts one of three ways: accepting a citation gap opportunity creates a candidate topic on the Articles screen (api/routers/citation_gaps.py#accept_citation_gap, api/services/citation_gap.py#create_article_topic_from_opportunity), you type your own title directly (api/services/articles.py#submit_custom_topic), or you press Write a page on a search plan topic, which fills in that same form and links the article to the topic (frontend/src/lib/search-plan.js#writePageHref). Either way, nothing is written until you pick it: choosing a suggested topic or submitting your own is what creates the Article row and starts generation (api/services/articles.py#select_topic, api/tasks.py#generate_article_task). How many articles you can start in a week is bounded by your plan; see Pricing for what each plan includes (api/services/limits.py#check_article_limit).

From a topic to a brief

Before anything is written, DiscoveredBy reads two sets of pages: the pages currently cited for the prompt behind the topic, and pages of yours: first the search plan topic's own page when the article came from Write a page, then up to five more of your own pages picked for this article, then the citation gap opportunity's own target page, pages already mapped to that prompt during gap analysis (an explicit mapping, a page of yours already cited for it, or a similarity match: api/services/citation_gap.py#_resolve_owned_page), and, filling out the rest, the project's own highest-scoring optimization opportunities that have not been dismissed, whether or not they relate to this particular topic (api/services/article_writer/corpus.py#_owned_pages). A page only counts once it is long enough to say something (api/services/article_writer/corpus.py#_useful_page). On a plan that grounds drafts in evidence, if fewer than two of the cited pages count yet and at least one of them still has no usable text, the brief itself waits: generation defers at most twice, 180 seconds apart, before a third and final attempt proceeds regardless of how many pages came back (api/services/article_writer/service.py#generate_article_with_writer, api/tasks.py#_run_generate_article, api/tasks.py#MAX_ARTICLE_GENERATION_ATTEMPTS). A topic you typed yourself has no prompt behind it, so it has no cited pages to wait on.

A topic from Write a page does have one: of the search plan topic's tracked prompts, the one whose answers cited other sites most often in the last 30 days (the window the writer reads cited pages from), or the oldest of them when none was cited (api/services/articles.py#_best_evidenced_prompt_id).

Your own pages are picked once per article, before the brief. The list comes from the Sitemap lines in your robots.txt, or from /sitemap.xml when there are none, keeping only pages on your own domain, shallowest paths first, up to 400 (api/services/article_writer/site_pages.py#sitemap_page_urls). A model then picks up to five that most likely say what you offer for the question, how it works, proof such as case studies, and how a buyer contacts you. It answers with numbers from that list, never with addresses of its own, and anything outside the list is dropped (api/services/article_writer/site_pages.py#choose_site_pages, api/services/article_writer/site_pages.py#picked_site_pages). A site with no readable sitemap, or a failed pick, leaves the writer with the pages above. A rewrite picks again.

Your own pages have a wait of their own, on every plan: when the topic's page or a picked page has never been scraped, generation defers on the same schedule until it has been, so nothing about your business is written without them. Those pages are scraped ahead of the queue of other pages waiting to be read, and a page whose scrape failed is not waited for (api/services/article_writer/corpus.py#_pending_own_page_ids, api/tasks.py#_enqueue_web_pages). Your approved brand facts from Fact check go to the writer as well (api/services/article_writer/corpus.py#_brand_facts).

The brief itself decides the asset, not just the content: which asset to build, from updating a page you already own to publishing something new to holding off entirely, starting from a deterministic guess based on the gap's own diagnosis and the prompt's shape and then confirmed or overridden by the writer (api/services/article_writer/asset_decision.py#deterministic_asset_recommendation, api/services/article_writer/briefs.py#brief_prompt). Four outcomes get drafted: a brand new article, a comparison page, a service page (shown as "Product page"), and an update to a page you own. An update is drafted only when the writer has that page's scraped text to rewrite: the page the brief names when it is one of yours the writer has read, otherwise the first of your pages listed above (api/services/article_writer/asset_decision.py#can_draft_asset, api/services/article_writer/asset_decision.py#update_target_page). For a docs page, an FAQ-only addition, holding off entirely, or an update whose page the writer could not read, the brief itself is the deliverable: why that page and not a new one, what the cited pages have that yours does not, and what sections or proof to add, with no markdown draft to copy. Such an article reads "Brief only" rather than "Ready" (frontend/src/lib/article-status.js#getArticleStatus).

You can overrule the writer's choice. The "Write your own topic" form and Rewrite both have a "Write as" choice: the writer decides, a new article, a comparison page, a product or service page, or an update to a page of yours. The brief and draft then follow that choice, even when the brief call itself fails, and on an article the choice stays selected for the next Rewrite until you change it (api/services/articles.py#submit_custom_topic, api/services/articles.py#regenerate_article, api/services/article_writer/briefs.py#normalize_brief_payload).

A service page or a page update is written as copy for your own site, not as an article. On every plan, every draft (an article too) is shown up to six of your own pages listed above and your brand facts, and a page update also gets the page it rewrites, read whole. A service page answers the buyer's question in your own voice; an update keeps what the existing page already says. The draft is meant to be published as it stands: it states a fact about your business only when one of your pages or brand facts says it, and it carries no bracketed placeholders, no notes to an editor and no em dashes: one the model writes anyway becomes a comma in the page, its meta description and its FAQ (api/services/article_writer/drafting.py#normalize_draft_payload). Something the brief wanted that nothing you have published supports, such as a client result or a price, is left out of the copy and listed under "Fill the gaps" beside the draft (api/services/article_writer/drafting.py#draft_prompt). A bracket the writer leaves in anyway is a blocker (api/services/article_writer/readiness.py#citation_readiness).

When it stops and asks you first

On a plan where the draft is meant to be grounded in real source pages, and only when the brief calls for a brand new article or a comparison page (not a service page, and not an update to a page you own), generation can pause instead of drafting: when the brief itself asks for proof only you can supply, such as pricing or customer proof it has no way to invent on its own (api/services/article_writer/briefs.py#_owned_input_requests), when it flags that it needs your input outright, or, failing safe the same way, when the brief call itself did not come back, rather than let a full draft get written from a generic fallback brief with no real proof behind it (api/services/article_writer/service.py#_should_pause_for_user_input). When that happens the article's status reads "Needs your input," and the page says plainly that the brief is ready but the draft needs proof only you have. When the brief actually named what it needed, that proof is listed under "Proof only you have" so you know what to add before you rewrite it. The other two triggers do not guarantee anything there: the model can flag that it needs input without naming what, and a failed brief call falls back to a generic brief whose own request list is empty unless the prompt is pricing, vendor, or comparison-shaped (_owned_input_requests names five of the nine prompt intents; the rest, including the default, get nothing). In either case no proof list appears, and the status and the instruction to rewrite are what you have to go on. On other plans, or for any other outcome, generation never pauses this way. A service page or a page update is left out on purpose: a page about your business always needs facts only you have, so pausing would mean it is never drafted. It is drafted from what your pages and brand facts say, with the rest listed under "Fill the gaps".

If the writing model does not return a draft, because it timed out or failed, the article is marked Failed with the reason, and Rewrite tries again. Nothing stands in for the missing draft (api/services/article_writer/service.py#generate_article_with_writer).

Grounding and claim checks

A draft is written only from the brief and the pages already read for it, with an instruction not to reuse a competitor's own phrasing or claims (api/services/article_writer/drafting.py#draft_prompt). Every claim the writer reports gets one of six labels, and what decides the label is whether the writer is allowed the last word on it. Four labels stand as the writer reported them: that a claim needs your own proof, that it conflicts with the source, that it rests on a source that may be stale, or that its wording is promotional. Any claim not carrying one of those four goes through a deterministic test, and the label it comes out with is the code's. It earns "verified by source" only when its quoted evidence is at least four words long, appears in the actual scraped text of the source page it names, and shares real terms with the claim it is supposed to back, so a fabricated statement paired with a generic quote does not pass. Your own pages the draft was shown, and your brand facts, count as sources here too, so a claim quoting what your site or your facts already say can be verified (api/services/article_writer/drafting.py#own_evidence). Words are compared without punctuation or a plural "s", so "React," in a claim matches "React" in its quote; at least two words of four letters or more must still be shared (api/services/article_writer/verification.py#_terms). Failing that, it is labelled "promotional" if its wording matches a fixed list of superlatives (best, leading, guaranteed, and the like), and "unsupported" if not (api/services/article_writer/verification.py#verify_claims, _quote_supports_claim, _is_promotional_claim). So the writer cannot certify its own work: "verified by source" and "unsupported" are the two labels only the code ever awards, and a claim the model hands back as verified whose quote fails the test comes out "unsupported" instead, or "promotional" if the wording is superlative. The test only ever looks at the claims list the writer handed back, not the rest of the draft, so a factual statement in the prose that never made it into that list is not checked either way. No claim is ever dropped from the draft over any of this: what shows on the article is the label next to the claim's own text, and any claim that does not come out "verified by source" counts against the citation readiness score and raises one of the checks listed at the top of "Publish it" beside the draft (api/services/article_writer/readiness.py#citation_readiness).

Before you publish, and after

Every article that reaches "ready" status carries a publish checklist, even a brief-only outcome with no draft to copy: a suggested slug, title tag and meta description, which schema blocks actually validated and are worth including, internal links to add, and indexation steps to take once it is live (api/services/article_writer/publishing.py#publish_checklist). The suggested slug for a new page is the draft's own suggestion when none of your pages the writer knows of already uses it, otherwise the one from the draft's headline, otherwise the one from the article's title; when every one is taken, the checklist names the page that already has it, so you choose another. For a page update the slug gives way to the page to update, which keeps its URL, the indexation steps say so, and that page is not listed among the pages that should link to it. A service page or a page update never lists Article schema, which describes an article rather than a page about your business (api/services/article_writer/service.py#generate_article_with_writer). An article paused at "Needs your input" has no checklist yet: generation stops before one is ever built, and it only appears once you rewrite the article past that point. DiscoveredBy never publishes the page for you. You copy the draft out, or, on Starter and up, send an article straight into a connected WordPress site as a new draft post with one click (a service page or a page update is not a post, so it is not sent: api/services/cms/wordpress.py#send_draft), carrying over the article's own title and meta description plus the checklist's suggested slug; see WordPress drafts for what that does and does not do. Either way, the draft still has to be put live on your own schedule, inside WordPress or wherever else it belongs, before it links to anything here: paste the live URL back in afterward. For an article written from a citation gap that is still open, doing that links the article back to that gap, moves the opportunity into monitoring right away, and records the day 7, 14 and 30 checkpoints it will be compared against once something checks back (api/services/articles.py#update_article_publication, _attach_publication_monitoring). Outcome checks exist only for citation gaps, so nothing else is measured: an article from the search plan's "Write a page" has a prompt but no gap, a dismissed gap is never checked, and a topic you typed yourself has neither. "Track it" says which case you are in before you save the URL and after: "Saved, but nothing measures this page" for those, the checkpoints while checks run, and that measuring has finished once the gap has its verdict (api/services/articles.py#publication_monitoring_payload).

What you see

Two controls sit in the page header: a button that turns weekly suggestions on or off for this project, and the day they arrive (api/routers/articles.py#update_article_schedule). Turned on, a daily job picks up the projects whose chosen day is today and generates that week's topics for them (api/tasks.py#_enqueue_weekly_topics_for_eligible_projects). Turned off, that job skips your project entirely (api/tasks.py#_run_generate_topics_for_project).

The day is UTC, not your local timezone. A project that has never set a day gets one derived from its id, so not every account lands on Monday (api/services/articles.py#scheduled_day_for_project).

Suggestions arrive at most once a week per project, even if that job runs again in between: a project that ran within the last six days is skipped (api/tasks.py#WEEKLY_TOPICS_MIN_INTERVAL_DAYS). Neither control gates either of the two paths above, which are what put a topic on this screen.

Articles opens on the strongest topic still waiting on you, ranked by the topic's own opportunity score when one exists (api/routers/articles.py#list_article_topics; see "What the numbers mean" below for what that score is not), with a button to start it, or, if it already has an article, to open the draft instead, plus two tiles counting finished drafts ready to publish (a "Brief only" article is not one) and ones still queued or being written (frontend/src/lib/article-view.js#readyDraftCount). Where the plan has a weekly article allowance the screen shows how much of it this week has used, such as "1 of 4 articles this week", and once it is used up, or the plan has no articles, every button that starts writing is disabled with the reason beside it, the same message the API would give (frontend/src/lib/article-view.js#articleQuota). Rewriting an article you already have is not counted against the week and stays available. If the topics cannot be loaded the screen says so and offers Retry instead of reporting no suggestions. Other topics list below it, and a form lets you start from your own title and angle at any time. Below that, your 50 most recent articles, each with its status ("Brief only" when there is no draft) and a readiness score once one exists, which is also the list the two tiles are counted from.

Each article's own page leads with the draft itself, as it will read on your site, under its status, the kind of page it is and its address, and one line saying how many of its claims a source backs, how many facts it left out, and its readiness score (frontend/src/lib/article-view.js#claimCounts, frontend/src/lib/article-view.js#pageAddress). Beside the draft (below it on a phone) are "Publish it", with what to check first, the address, page title, meta description and structured data to copy, the steps once it is live and, for an article, a WordPress draft; "Fill the gaps"; "Track it", where the live URL goes; and "What it read", with your pages, the cited pages and every claim check, the ones without a source first. The writer's plan sits closed under the draft as "How the writer planned it". A brief with no draft shows the brief where the draft would be. Rewrite, with its "Write as" choice, and Copy markdown sit at the top of the page. Rewrite asks first, because the draft, brief, claim checks, publishing checklist and the pages it read are all replaced and the current version is not kept; the dialog offers Copy markdown to keep it. Deleting an article asks first too. While an article is being written its page checks back on its own and updates when the draft is done.

What the numbers mean

Citation readiness, out of 100, starts full and loses points for a thin source corpus, for claims left unsupported or unresolved, for FAQ schema that failed to validate, and for a draft that reads short (api/services/article_writer/readiness.py#citation_readiness). Read it as a checklist score for this one draft, not a ranking against other articles. A brief has no score: there is no draft to grade. It used to be graded as though its missing body were a short draft, which put 65 out of 100 on a page with no words (api/services/article_writer/service.py#generate_article_with_writer).

A topic's opportunity score is a different figure from the opportunity score on Optimizations, which scores one of your pages out of 100 and ranks it against your other pages: the two are separate numbers that happen to share a name, so a figure there does not translate into one here. This one belongs to the topic, comes from the citation gap opportunity behind it (api/services/citation_gap.py#create_article_topic_from_opportunity), and is what orders the topic list above, strongest first (api/routers/articles.py#list_article_topics).

It is now carried across on the gap's own scale of 1 to 100, unchanged, which is what lets the badge beside the leading topic read as a real score out of 100 (frontend/src/routes/(app)/articles/+page.svelte#topScore). The same code used to divide that score by 100 before storing it, so every topic created this way held a fraction below 1, and a badge rounding it to a whole number could only ever print 0 or 1. Only topics written after that correction carry the new scale: rescaling the rows already stored is a separate database step, not something the code change does on its own. A topic you typed yourself has no score at all (api/services/articles.py#submit_custom_topic records none), and the screen says "Suggested this week" with no badge rather than showing a zero when the leading topic is one of those.

For how to read a change against a baseline in general, see How to read any number here.

  • Citation gaps: where a topic comes from, and how accepting one hands it to the writer
  • Optimizations: the other route from a citation gap, for when the fix is smaller than a new page
  • Metrics defined: the citation concept behind the prompt an article is written to win
  • WordPress drafts: sending a finished draft into WordPress instead of copying it out by hand
  • Pricing: how many articles a week your plan includes

Last verified 2026-10-14

Start monitoring your AI visibility.

See how AI search engines talk about your brand.

Free to start. No credit card required.