> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yournarrative.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Keywords

> Where Narrative finds the searches your buyers make, how it decides which ones belong to your brand, and how each one is measured and scored.

A keyword in Narrative is a search people actually make, in one of your languages, that your buyer would plausibly type while looking for what you sell. Getting to that short list means starting from a long one and being strict about what survives. This page explains the whole route, from the first candidate to the tracked keyword on your Keywords page.

![Eight sources feed a candidate pool; two gates and the fit judge reduce it to the tracked keywords.](https://mintcdn.com/narrative-22c775b1/dln-O-8JryD9ZygN/images/figures/keyword-sources-light.svg?fit=max\&auto=format\&n=dln-O-8JryD9ZygN\&q=85\&s=0f62fae94d203fcbb924d656c0368c55)

Eight sources feed one pool. Two gates and a judge decide what is yours.

## Where candidates come from

Narrative collects candidates per language from eight sources, and every candidate keeps its lineage: which source produced it, and from which seed.

| Source | What it contributes |
| - | - |
| **Anchors** | The head terms you gave Narrative, such as *payment gateway* or *worker housing*. Where you left a slot empty, Narrative derives one from your products, audiences and differentiators. A head term is short, so it is kept to four words. |
| **Related searches** | What Google's keyword data lists as related to each anchor, several hops out. |
| **Suggestions** | The autocomplete suggestions each anchor produces. |
| **Seed ideas** | Narrative reads your catalogue, value propositions and audiences, writes a short list of seed phrases, and expands each of them through keyword data. This is usually the largest source. |
| **Rivals' keywords** | The searches each confirmed competitor already ranks for. Most of these are the competitor's own navigational and support traffic, which is why the gates below exist. |
| **Search Console** | Every query your site already earns impressions for, when Google Search Console is [connected](https://docs.yournarrative.ai/connectors/google-search-console.md). These are the searches Google has already decided you answer. |
| **Buyer questions** | Questions your buyer persona would ask, written in the persona's own words, in each language. |
| **AI fan-out** | The sub-queries AI assistants break your prompts into when they search the web to answer them. |

Two of these sources are written by a model rather than read from a provider. Their answers are kept, not regenerated: once Narrative has written your seed ideas and buyer questions, every later run reuses the same list until your brand itself changes. That is what keeps your keyword set stable from one week to the next.

Anchors, Search Console queries and anything you add by hand are **vouched**: they are scored like everything else but never rejected, because a person or your own traffic has already said the phrase matters.

## Two gates

The pool is large, thousands of rows per language, and most of it is not about you. Two cheap filters run first so that the expensive judgement is spent only on plausible candidates.

1. **The category gate.** Narrative extracts a vocabulary of category terms from your brand intelligence and anchors, one per language. A candidate is kept when it touches one of those terms, when two or more of your competitors rank for it on the first three pages, or when it names a competitor beside a comparison word. Arabic is matched by stem rather than by exact spelling, so one word's plural and singular count as the same term. Like the seed lists, the vocabulary is kept and reused until your brand changes.
2. **The noise gate.** Each survivor is compared against the seed that produced it and against the text of your own website. A candidate that resembles neither is set aside.

Both gates re-decide every run. A keyword one of them set aside comes back on its own if a later run keeps it, and it is recorded with the reason it was set aside, so when you ask why a keyword is not in your topics, there is an answer.

## The fit judge

The gates are filters. The judge is the verdict, and everything downstream inherits it.

Each surviving candidate is read with your products, value propositions, differentiators, audiences, persona, competitor names and exclusions in front of it, and given a **fit score** from 0 to 1 with a reason:

* **1.0** your persona would type this when looking for what you sell
* **0.7** an adjacent need you serve, and the query names something in your catalogue
* **0.4** your category, but a different buyer
* **0.1** unrelated, or a different sense of the word

The judge also labels the **kind** of query: a category need, a comparison, a generic head term, someone looking for a competitor by name, a job seeker, a support request, and so on. Each kind has a ceiling. A generic shopping word like *offers* or *gifts* cannot score above 0.4 however generously your brand is described, and a competitor's own navigational search cannot pass. Only the two kinds you have a reason to win, category needs and comparisons, are uncapped.

The verdict is **the middle of three independent readings** rather than a single one. Asked three times with different starting points, the stored verdict is the median, so one unlucky reading cannot keep a keyword out or let one in. A keyword at 0.5 or above is kept. One below it is rejected but keeps its score and its reason, so you can see what was dropped and why.

A verdict is permanent until the rubric or your brand changes. Narrative does not re-judge a keyword it has already judged, which is why a weekly rebuild does not reshuffle your set.

> [!NOTE]
>
> If the judge keeps keywords for a buyer or a use you do not serve, add an **exclusion** to your brand profile: the audiences, uses and adjacent categories you are not for. Exclusions are part of the judge's context, and the next run re-judges exactly the keywords the change affects.

## What each keyword is measured on

Once a keyword is yours, Narrative measures it. These are the columns on the Keywords page.

**Monthly volume.** One figure from one named source. Each language has an order of preference between providers, and the first one with an answer wins, including an answer of zero. A keyword no provider could price is left blank rather than written as zero, and it does not advance until a later run can price it. A keyword with a volume of zero is set aside unless your site already earns impressions for it or a person added it: an anchor is a statement of intent, and a provider's estimate of zero does not refute it.

**Search Console impressions and clicks.** When connected, the last 180 days of your own impressions and clicks sit beside the volume, matched across spellings so two forms of one Arabic phrase land on one row. A brand with no Search Console shows blank here; a connected brand with no impressions for a keyword shows zero. The two are not the same.

**The first page of Google.** For every measured keyword, Narrative fetches the top ten as a searcher in your country sees them, on your chosen device, along with the AI Overview when Google shows one. Every result page is classified by what kind of page it is: a guide or article, a product or pricing page, a category listing, a forum thread, a video, a news story, a homepage. Each page is classified once per run rather than once per keyword, so one URL carries one label.

**Intent.** Read off the results page rather than guessed from the words. If Google answers a query with ten guides, the query is informational; if it answers with product and pricing pages, it is commercial or transactional. From the same reading each keyword gets a funnel position (top, middle or bottom) and a navigational flag when the query is really someone looking for a brand by name.

**Difficulty.** A score from 0 to 100 for how hard the first page is to reach, from the strength of the domains already on it and how concentrated they are. A thin page of weak domains with no clear winner scores low, which is the easy-win case. Domain strength is cached and shared across brands, because a domain's authority is a fact about the domain.

**Who is winning.** Whether you are in the top ten, whether a tracked rival is, and whether the AI Overview cites you.

## The opportunity score

![Volume 30%, intent 25%, gap 25%, AEO 20%, multiplied by fit and by difficulty.](https://mintcdn.com/narrative-22c775b1/dln-O-8JryD9ZygN/images/figures/opportunity-score-light.svg?fit=max\&auto=format\&n=dln-O-8JryD9ZygN\&q=85\&s=5552d85a8fbe01d0e427ffaf4689d44a)

Four weighted parts, scaled by fit and by difficulty.

Every measured keyword gets one opportunity score from 0 to 1. Four parts are weighted and summed:

* **Volume** (30%): how many people search it, on a log scale so a head term does not drown everything else. For conversion-led goals this is priced by cost per click, so a thin but valuable B2B query ranks ahead of a large but worthless one.
* **Intent** (25%): where the keyword sits in the funnel, weighted by whether your goal is conversion or visibility.
* **Gap** (25%): where you rank today. Already in the top three scores low, because there is little to gain; absent from the first page while a rival holds a slot scores high.
* **AEO** (20%): whether the AI Overview and the AI assistants already cite you for it.

The sum is then multiplied by the keyword's fit score, so a keyword that is only half yours is worth half as much, and scaled by difficulty against your own standing: a first page you have no realistic way of reaching is discounted. A keyword missing any of its inputs (no fit verdict, no volume source, no intent) is left unscored rather than scored low.

The top 500 keywords per language by score become your **tracked** set, together with every keyword you added, pinned or already earn impressions for. The rest remain candidates, still visible, still measured next time.

## What you can do on the Keywords page

* **Reject a keyword** you do not want, with a reason. It leaves its topic and no rebuild brings it back.
* **Add it back** if you change your mind.
* **Move a keyword to a topic**, or into a new topic. Moving is a decision; clustering reads it as fixed from then on.
* **Add your own keywords**, one at a time or as a pasted list into a topic. They are tracked and pinned the moment you add them, and measured on the next run.
* Open any keyword to see the top ten it returned, what the AI Overview said, and the topic it sits in.

A status you set is yours. A keyword you tracked takes no slot in the 500 and is never demoted; a keyword you rejected is never promoted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.