Keyword Research

Build a keyword map grounded in search intent. Without paid API access, rely on SERP analysis, autocomplete patterns, and competitor pages. With seo-data-provider env keys, pull real volume/KD.

When to use

• New site / new market content plan
• Expanding clusters or languages (FR/EN/AR)
• Prioritizing which pages to create or refresh

When not to use

• Single-page title tweak (use on-page-seo-optimizer)
• Fabricating a "volume report" with no API or export

Intent types

Intent	Signal	Page type
Informational	how, what, guide	Blog / docs
Commercial	best, vs, review, pricing	Comparison / landing
Transactional	buy, demo, quote, brand+product	Product / contact
Navigational	brand names	Home / feature pages

Workflow

1. Seed list: products, services, pains, jargon from the user (FR + EN + AR when relevant).
2. If MCP search-console is connected, pull live queries/pages (impressions, CTR, position) for the property before estimating; treat GSC as ground truth over SERP guesses.
3. If seo-data-provider is available, pull volume/KD/related; else expand via web_search (variants, PAA themes, related searches).
4. For each candidate, inspect the SERP: who ranks (giants vs niche), format (listicle, landing, video).
5. Estimate difficulty qualitatively without API: Low / Medium / High from domain strength + content depth needed. Never invent numeric KD or monthly volume.
6. Cluster by topic; assign one primary keyword + secondaries per target page.
7. Save seo/keyword-map-<topic>-<date>.md (and CSV if useful).

Keyword map format

| Cluster | Primary keyword | Intent | Difficulty | Volume | Target page | Priority | Notes |
|---------|-----------------|--------|------------|--------|-------------|----------|-------|

• Volume: integer from API/export, or n/a (requires API data)
• Difficulty: Low/Medium/High (qualitative) or API KD if sourced
• Priority: P1/P2/P3 by business value × winnability

Rules

• Prefer MCP search-console live data over CSV or estimates when the preset is connected (Settings → MCP).
• Never invent volume numbers; say estimate or requires Ahrefs/Semrush/DataForSEO/GSC.
• One primary keyword per page - no cannibalization.
• Prefer money-intent clusters when the goal is leads/sales.
• Pair with seo-content-writer for execution and competitor-seo-analysis for gaps.

Anti-patterns

• 500-keyword dumps with no clusters or page owners
• Copying competitor keyword lists without SERP checks
• Treating brand navigational queries as content opportunities