Your job is to identify gaps in SEO/AEO for [YOUR BRAND]. I.e. what prompts/queries should be mentioning/returning [YOUR BRAND] but are not?

If the user has not already provided a topic and article type, brainstorm together with them. You may find it helpful to reference:

• Your system prompt with platform information on [YOUR BRAND]
• [MORE YOUR BRAND RESOURCES]

Page types include:

Page type	Primary intent	What to look for in Step 2
[Competitor] alternatives roundup	Switching / evaluation	Complaints about the competitor (pricing, complexity, gaps)
Best [category] tools listicle	Evaluation	Recommendations, "what do you use for X" threads, praise & complaints per tool
[A] vs [B] comparison	Decision	Head-to-head experiences, migration stories
Pricing guide ([Product] pricing)	Research	Real invoice/contract anecdotes, "is it worth it" threads
How-to / guide	Informational	Questions people actually ask, failed-approach stories
Glossary / definition	Informational	How practitioners actually use the term

The AHREFS_API_KEY is already set for this step.

1. Build the keyword set around the topic, such as [topic], best [topic], [topic] tools/software, [topic] free, [competitor] alternatives, [A] vs [B], [topic] pricing, [topic] api, plus question forms of the keyword
2. Pull volume, keyword difficulty, CPC for the whole set using the Ahrefs v3 GET /keywords-explorer/overview (or /site-explorer/organic-keywords for pages that already rank). Both endpoints require a select parameter (comma-separated list of fields to return). For keywords-explorer/overview, use "keywords,volume,global_volume,difficulty,cpc,traffic_potential,intents". Note: CPC is returned in USD cents (e.g., 400 = $4.00) — divide by 100 for display. The parameter is keywords (plural, comma-separated), not keyword (singular). The response is wrapped in { "keywords": [...] }. You can batch multiple keywords in one call, but keywords with no data are omitted from the response (not returned with zeroes).
3. Use the Ahrefs v3 GET /keywords-explorer/matching-terms with keywords= and terms=questions to discover question-form queries people actually search for around broad seed keywords (e.g., "deploy web app", "host api"). This is more efficient than guessing question forms — pass match_mode=terms and order_by=volume:desc to get the highest-volume questions first.
4. Check the site's current rankings for the set (Ahrefs site-explorer/organic-keywords with mode=exact|prefix, select="keyword,best_position,volume,keyword_difficulty,sum_traffic,cpc,is_informational,is_commercial,is_transactional")
   • you may recommend refreshing an existing page instead of building a new one
5. Read SERP by web search. Our Ahrefs Lite plan returns no SERP data, so there is no API for this - instead, search the primary keyword and read the results for:
   • Format: what page type ranks (roundup, guide, product page)?
   • Length norms: how many items do ranking lists include?
   • AI Overview: do results have a clean, citable definition/answer block near the top?
   • People Also Ask: is there a list of FAQs or other questions?
   • Who ranks: note opportunities (stale dates, no pricing, no primary sources)
6. Cannibalization check: do we already have a similar page (on val.town, blog.val.town, or docs.val.town)?
7. Decide and record: target keyword, secondary keywords, page format, list length, title (include the year for evaluation keywords)
8. Save the research report in ./research, formatted as YYYY-MM-DD-[topic].md with contents: Keyword | Volume | KD | CPC | Intent table, SERP notes, the decision and what was rejected, quote shortlist, verified pricing, API cost footer, and anything learned

The OCTOLENS_API_KEY is already set for this step.

1. Use the Octolens POST /api/v2/mentions to search the full archive of Val Town mentions. It covers Reddit/HN/X/Bluesky/LinkedIn going back as far as collection does. Uses Bearer auth, Body: {"filters": {"startDate": "...", "endDate": "..."}, "limit": 100, "cursor": "..."}, ISO 8601 dates, cursor-paginate. Note: The base URL is https://app.octolens.com (not api.octolens.com, which returns 404). If the API continues to fail, fall back to web_search for Reddit/HN coverage.
2. Search for competitor and category terms using the search field on POST /api/v2/mentions (free-text across title, body, author handle, and author name). The search field only covers mentions already tracked by Octolens, so for comprehensive coverage of competitor/category conversations, use web_search as the primary tool. Search Reddit, HN, and blogs for tool comparisons, pricing complaints, and "what do you use for X" threads.
3. Select quotes relevant to the topic that name a specific win or pain (price figures, missing features, wasted time), use searcher language, and where possible mention multiple products at once. Verify every URL is live and public - we will not include a quote that we can't source. Record quotes in the research file, and note if there weren't many.

Exclude quotes from the [YOUR BRAND] team.

If you created any scripts/files in steps 2 and 3, you can delete them once the report is ready.

Once the user has agreed to your list of keywords, create an evals suite in ./evals. The file name should be formatted as YYYY-MM-DD-[topic].ts.

If you learned anything during this process, like gotchas with the Octolens API, propose changes to this document.