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

# SEO

> Research keywords, discover opportunities, and plan content based on search demand.

## Overview

SEO helps you discover, evaluate, and act on keyword opportunities. It connects to Ahrefs for keyword research, scores and clusters keywords into page-targetable groups, and flags potential conflicts with your existing content.

Navigate to **SEO** in the Tools section of the sidebar.

## Tabs

### Opportunities

The Opportunities tab is your command center for keyword research:

* **Summary Cards** — Total keywords, active clusters, top opportunity score, and API units used this month.
* **Quick Research** — Enter seed keywords, choose expansion modes (Ideas, Related Terms, Autocomplete Suggestions), and click Research to discover new keywords via Ahrefs.
* **Cluster Table** — Top-scoring keyword clusters ranked by opportunity score. Each row shows cluster name, type, keyword count, total search volume, average difficulty, commercial score, and conflict status.

**Actions:** Promote a cluster to create an idea candidate (landing page, blog post, or comparison page), or re-run scoring, clustering, and conflict detection from the action buttons.

### Commercial Map

Filtered view showing only **commercial** and **comparison** clusters — the keywords with direct revenue potential:

* Each cluster card shows top keywords with volume, average CPC, difficulty gauge, and conflict warnings.
* Filter by minimum volume, maximum difficulty, and conflict severity.
* **Promote** directly to a Landing Page or Comparison Page idea candidate.

### Content Map

Filtered view showing only **content** and **FAQ** clusters — the keywords for blog posts and educational content:

* SERP feature badges (Featured Snippet, People Also Ask) help identify quick-win opportunities.
* BOFU/MOFU tags indicate buyer-journey stage based on intent mix.
* **Promote** directly to a Blog Post idea candidate.

### Keyword Library

Full searchable table of all keywords in your repository:

* **Columns:** Keyword, search volume, difficulty, CPC, search intent, GSC impressions, ads conversions, opportunity score, commercial score, cluster, status.
* **Filters:** Text search, intent type, source, cluster, score ranges, status.
* **Detail Panel:** Click any keyword to see full metrics, SERP features, and first-party data in a slide-out panel.

## How Scoring Works

Every keyword receives two scores:

| Score                         | What it measures  | Key factors                                                                                  |
| ----------------------------- | ----------------- | -------------------------------------------------------------------------------------------- |
| **Opportunity Score** (0-100) | Overall potential | Search volume, keyword difficulty (inverted), GSC demand, traffic potential, ads conversions |
| **Commercial Score** (0-100)  | Revenue potential | CPC, ads conversions, commercial/transactional intent, commercial modifier keywords          |

Scores use percentile normalization across all your keywords — a score of 75 means this keyword is better than 75% of your other keywords on that dimension.

## How Clustering Works

Keywords are automatically grouped into clusters using embedding similarity (K-Means). Each cluster is classified:

| Cluster Type | Page Suggestion | How Detected                                         |
| ------------ | --------------- | ---------------------------------------------------- |
| Commercial   | Landing Page    | 60%+ commercial/transactional intent                 |
| Content      | Blog Post       | 60%+ informational intent                            |
| Comparison   | Comparison Page | 30%+ comparison modifiers (vs, compare, alternative) |
| FAQ          | FAQ Page        | 40%+ question modifiers + informational intent       |

## Conflict Detection

Before you create new content, the system checks for overlap between keyword clusters and your existing assets using three signals: content embedding similarity, GSC ranking overlap, and focus keyword matches.

| Severity                       | What it means                                                                                |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| **None** (green)               | No significant overlap — safe to create                                                      |
| **Low** (yellow)               | Minor similarity — review existing content first                                             |
| **Medium** (orange)            | Moderate overlap — consider consolidating                                                    |
| **High / Covered** (red/amber) | Strong overlap or exact focus keyword match — you likely already have content for this topic |

Clusters where an existing asset's focus keyword exactly matches a cluster keyword are automatically marked as "Covered" with an amber badge and visually deweighted in the map views.

## Dismissing Clusters

You can dismiss clusters you don't want to target. Dismissed clusters appear grayed out with a "Dismissed" badge. Use the **Show dismissed** toggle to hide or reveal them.

* Click the **X** button on any cluster row to dismiss it
* Dismissed clusters can't be promoted
* The toggle defaults to hidden, keeping your map views focused

## Promoting to Ideas

When you promote a cluster, it creates an **Idea Candidate** pre-filled with:

* Suggested title based on cluster keywords
* Target keywords and search volume
* Recommended page type
* SERP feature opportunities

From there, use the existing Promotion Wizard to create a full content brief.

## Automatic Seed Discovery

The system automatically discovers high-signal keywords from your first-party data, filters for relevance, fetches metrics from Ahrefs, and adds them directly to your keyword library. No manual keyword entry required.

### How It Works

Three data sources are mined for keyword seeds:

| Source                    | What It Finds                                                                                       | Example                                                    |
| ------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Google Search Console** | Queries where you rank position 5-30 with decent impressions — keywords you're *almost* ranking for | "best crm for agencies" (position 12, 800 impressions)     |
| **Google Ads**            | High-converting search terms — keywords already driving revenue                                     | "agency management software" (3 conversions, 15 clicks)    |
| **Entity Coverage Gaps**  | Your entities with high demand but low content coverage, ranked by pre-computed priority score      | "client onboarding" entity (high priority, only 1 article) |

### What Happens Next

Seeds are scored, filtered for relevance, and ingested with metrics:

1. **Discovery** — Each source scores keywords independently (0-1 scale). Up to 200 seeds are discovered (no artificial cap). Keywords appearing in multiple sources get a bonus.
2. **Dedup** — Removes keywords you already have in your library.
3. **Relevance filter** — Seeds are checked against your site's domain vocabulary (entity names, existing keywords, website name). Off-topic seeds are dropped before any API calls.
4. **Budget check** — Small batches are processed automatically. Large batches (>5,000 API units) create a proposal for your review in the Experiments page.
5. **Metrics ingest** — Seeds are sent to Ahrefs for keyword metrics (volume, difficulty, CPC, intent), then scored, clustered, and checked for conflicts. This is 5x cheaper than full expansion because it fetches metrics only.

### Running Auto-Seed

* **Automatic:** Runs weekly (Wednesday mornings). Results appear in Keyword Library with the "Auto-Seed" source tag.
* **Manual:** Click **Run Auto-Seed** on the Opportunities tab. Choose "Discover Only" to preview seeds without expanding, or let it run the full pipeline.
* **History:** Recent runs are visible in the collapsible "Recent Auto-Seed Runs" section on the Opportunities tab.

### Filtering Auto-Seed Keywords

In the Keyword Library, use the **Source** filter dropdown and select **Auto-Seed** to see only keywords discovered through this pipeline.

## Enriched Clusters

Keyword clusters are automatically enriched with strategic context:

* **Topic Label** — A human-readable name like "CRM Selection for Small Business" (replaces raw keyword fragments). AI-generated labels are marked with a subtle indicator.
* **Primary Question** — The core question searchers are asking, e.g., "Which CRM is the right fit for a small business?"
* **Content Angle** — Suggested strategic approach, e.g., "Evaluation guide addressing cost and complexity"
* **Funnel Stage** — Where in the buyer journey, e.g., "mid-funnel — evaluating options"
* **Intent Bar** — Visual breakdown of search intent (informational, commercial, transactional) shown on every cluster.

These fields appear on cluster tables, cluster cards, and the cluster detail panel.

## SEO-Aware Content Generation

When you create content from an SEO cluster (via Promote), the system carries the full keyword context through every stage:

### What's Threaded

| Data               | Where It's Used                                                            |
| ------------------ | -------------------------------------------------------------------------- |
| Primary keyword    | Outline structure, draft H1, SEO title, URL slug                           |
| Secondary keywords | Distributed across outline sections, natural placement in draft            |
| Search intent      | Tone and structure guidance (educational vs. comparison vs. transactional) |
| Content angle      | Strategic direction for the piece                                          |
| Primary question   | Answered directly in the introduction                                      |

### How It Works

1. **Promotion** — When you promote a cluster, the full SEO context (keywords, intent, metrics, strategy) is saved with the new asset.
2. **Outline Generation** — The outline builder receives keyword targets and structures sections to cover them. Intent-specific guidance shapes the structure.
3. **Draft Generation** — The copywriter receives keyword placement instructions and tone guidance matching the search intent.
4. **Quality Evaluation** — A keyword alignment dimension checks that the primary keyword appears in key positions and secondary keywords are distributed naturally.

No manual keyword entry required — everything flows automatically from the cluster.

## Pre-Publish SEO

When publishing SEO-sourced content to WordPress, the system automatically:

* **Generates SEO metadata** — Title tag, meta description, and focus keyword are created from the cluster context if you haven't set them manually. This uses template logic (not AI) for speed and consistency.
* **Sets the URL slug** — Derived from the primary keyword (e.g., "best crm for small business" → `/best-crm-small-business`).
* **Links keywords** — After publishing, all keywords in the source cluster are linked to the published asset for performance tracking.

You can always override the auto-generated metadata before publishing.

## SEO Context in the Editor

Assets created from SEO clusters show their keyword context throughout the workflow:

* **Asset List** — A search icon and keyword badge appear on SEO-targeted assets in the content table.
* **Editor Sidebar** — Click the blue "SEO" button to open a panel showing the full SEO target: topic, keywords, intent breakdown, metrics, and strategic direction.
* **Optimization Tab** — An "SEO Target" card appears showing the keyword context alongside performance metrics.

This is read-only reference — the writer sees what they're targeting while working on the content.

## Keyword Tracking

After publishing, keywords from the source cluster are linked back to the content asset:

* In the **Keyword Library**, linked keywords show an asset link in the detail panel.
* In the **Cluster Detail** panel, promoted clusters show "Promoted to content asset" with a link.
* Future: ranking position and traffic tracking from Google Search Console data.

## Automatic Refresh

Keywords are automatically refreshed monthly:

1. Ahrefs metrics updated (volume, difficulty, CPC, SERP features)
2. First-party data enriched (GSC impressions/clicks, Google Ads conversions)
3. Scores recalculated
4. Conflicts re-detected

High-opportunity clusters also appear in your **Revenue Intelligence Inbox** as work items.

## API Usage

The Usage section (visible in the summary cards) tracks Ahrefs API unit consumption. The system reserves separate budgets for monthly keyword refreshes and weekly auto-seed discovery, while leaving units available for your interactive research.