> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Opportunities Engine: AI-Powered Visibility Insights
> Automatically surface competitor gaps, quick wins, content opportunities, and technical fixes ranked by impact and effort across your AI visibility data.
The Opportunities Engine analyzes your Visibility Analytics and API Performance data and surfaces specific, actionable improvements ranked by expected impact and implementation effort. Instead of manually reviewing dashboards and guessing what to fix, you get a prioritized list of changes you can act on immediately.
## What the Opportunities Engine does
Every day, after your prompt runs complete, the Opportunities Engine scans your results and looks for patterns across four opportunity types. It compares your mention rates, share of voice scores, and API Performance grades against your competitors and against known best practices for AI discoverability. It then generates a list of opportunities with an explanation of why each matters and what to do about it.
The goal is to compress the gap between "I see a problem in my data" and "I know exactly what to do."
## The four opportunity types
Prompts where a competitor is being recommended and you're not. These are the highest-priority opportunities because they represent active adoption you're losing.
Low-effort improvements with disproportionate impact. These are typically technical fixes — a missing `llms.txt`, a blocked AI crawler, an unclear error message — that take under an hour to resolve but meaningfully shift your scores.
Topics and use cases where you have no documentation coverage but competitors do. Answer engines and coding agents can't recommend you for prompts where your content doesn't exist.
Infrastructure-level issues that block AI discovery or usability: `robots.txt` rules that block AI crawlers, a missing or incomplete `llms.txt` file, generic error messages that prevent agent error recovery, and similar issues.
## Accessing and reading opportunities
Open the **Opportunities** section in your Lightsage dashboard. Opportunities appear as a list with the following fields for each item:
* **Type** — Competitor gap, Quick win, Content opportunity, or Technical fix
* **Description** — A plain-language explanation of what's happening and why it matters
* **Affected prompts** — Which of your tracked prompts are impacted
* **Estimated impact** — How much your Visibility Score or API Performance grade could improve if you address this
* **Estimated effort** — Low (under 1 hour), Medium (1 day), or High (1+ week)
* **Recommended action** — What to do, with a link to the relevant guide
## The priority/effort matrix
The Opportunities Engine plots every opportunity on an impact-vs-effort matrix. The top-right quadrant — high impact, low effort — contains your highest-priority items.
| | Low effort | High effort |
| --------------- | ----------------------- | ----------------- |
| **High impact** | Act on these first | Plan and schedule |
| **Low impact** | Do if you have capacity | Deprioritize |
Technical fixes almost always appear in the high-impact, low-effort quadrant. Adding an `llms.txt` file takes 30 minutes and is one of the highest-leverage changes you can make for coding agent discoverability. Fixing a `robots.txt` that blocks AI crawlers takes 5 minutes and can recover visibility across all 17 platforms at once.
Content opportunities typically appear in the high-impact, medium-effort quadrant. Writing a comparison page takes a few hours but pays off across every AI platform that surfaces comparison content.
Start every week by reviewing the top three opportunities in the high-impact, low-effort quadrant. Addressing these consistently compounds over time — small improvements to technical accessibility, positioning, and error messages add up to significant score changes over 30–60 days.
## Opportunity types in detail
Competitor gap opportunities identify specific prompts where a competitor is mentioned and you are not. Each gap shows:
* The prompt text
* Which competitor is winning it
* Which AI platforms are recommending the competitor
* Your current mention count for this prompt vs. the competitor's
Acting on competitor gaps usually involves one of: improving your documentation for the relevant use case, creating comparison content that positions you for the query, or fixing a technical issue that's preventing you from appearing.
Quick wins are opportunities where the expected improvement is high relative to implementation time. Common quick wins include:
* **Missing `llms.txt`**: You don't have a machine-readable API summary at your domain root. Coding agents use this file to understand your API before recommending it. Adding it takes 30 minutes.
* **AI crawler blocked**: Your `robots.txt` blocks `GPTBot`, `ClaudeBot`, or `anthropic-ai`. This prevents answer engines and coding agents from reading your documentation entirely. Fix takes 5 minutes.
* **Generic error messages**: Your API returns `Error 500` or `Bad Request` without explanation. Coding agents can't recover from opaque errors, so they switch to a competitor. Writing better error messages takes 1–2 days but significantly improves your API Performance grade.
* **Missing comparison page**: You don't have content for "\[Your API] vs \[Competitor]" queries that AI systems are actively surfacing. Adding one page can shift your share of voice on comparison queries noticeably.
Content opportunities surface topics where competitors have documentation coverage and you don't. These are identified by analyzing which prompts competitors win that you never appear in — even when you have a relevant product.
A content opportunity might look like: "Codex recommends \[Competitor] for 'add authentication to FastAPI app' prompts. You have no FastAPI-specific documentation. Creating a FastAPI quick start could win you these prompts."
Each content opportunity links to the Content Generation feature so you can generate a draft immediately.
Technical fixes are infrastructure-level issues that Lightsage detects by checking your domain directly. The Opportunities Engine scans for:
* **`robots.txt` issues**: AI crawlers blocked by `User-agent: GPTBot` or `User-agent: ClaudeBot` directives
* **`llms.txt` quality issues**: You have a file but it's missing key sections (use cases, quick start, key endpoints)
* **Client-side rendering**: Your documentation doesn't render without JavaScript, making it invisible to crawlers
* **Error message quality**: Based on API Performance data, your error messages aren't descriptive enough for agents to recover from failures
Technical fixes always appear with a direct link to the relevant guide explaining how to implement the fix.
## Content Generation
When an opportunity involves creating new content, you can generate a first draft directly from the Opportunities Engine. Select an opportunity and click **Generate Content**.
Lightsage generates AI-optimized content based on:
* The specific prompt or use case the opportunity targets
* Your brand kit (tone, positioning, terminology — see below)
* What competitors have written that's working for this query type
* Best practices for AI-readable documentation structure
Generated content types include:
* Comparison pages ("\[Your API] vs \[Competitor]")
* Use case quick starts ("Add \[Your API] to a FastAPI app")
* `llms.txt` files with your API's key endpoints and positioning
* Error message rewrites for your most common failure responses
Generated content is a starting draft — review it and add any product-specific details before publishing. The goal is to give you 80% of the work done so you can focus on the 20% that requires your specific product knowledge.
## Brand kits
A brand kit stores your messaging guidelines so generated content stays consistent with how you describe your product. You can configure:
* **Company and product name** — how you want your brand referred to across all generated content
* **Core value proposition** — one to three sentences that define your positioning
* **Key differentiators** — the 3–5 reasons developers choose you over alternatives
* **Tone guidelines** — formal vs. conversational, technical depth, audience assumptions
* **Terminology preferences** — preferred terms and terms to avoid
Set up your brand kit in **Settings → Brand Kit**. All content generated from the Opportunities Engine uses your brand kit automatically.
If you don't have a brand kit configured, Lightsage will still generate content — it will infer your positioning from your existing documentation and website. Setting up a brand kit takes 10 minutes and meaningfully improves the quality and consistency of generated outputs.
## Acting on opportunities
Each opportunity links directly to the relevant guide or action:
| Opportunity type | Where it links |
| ----------------------------------- | -------------------------------------------- |
| `robots.txt` fix | Guide: allowing AI crawlers |
| `llms.txt` missing | Guide: creating an `llms.txt` file |
| Comparison page needed | Content Generation with comparison template |
| Error message improvement | API Performance endpoint breakdown |
| Quick start missing for a framework | Content Generation with quick start template |
| Competitor gap on a specific prompt | Visibility Analytics prompt detail view |
Work through opportunities in priority order — high impact and low effort first. After you implement a fix, Lightsage will detect the change in your next prompt run and update the opportunity status automatically. If a fix works, the opportunity closes. If you close an opportunity manually (because you've decided not to address it), it won't reappear unless the underlying data changes significantly.