 |
 |
Overview
Search Console KPI cards with daily clicks/impressions chart, top movers, and per-site freshness. |
Queries
Top queries with clicks, impressions, CTR, position, period deltas, and opportunity badges. |
 |
 |
Pages
Page-level click and impression table with top growth and decline movers for prioritizing content updates. |
Opportunities
Ranked SEO opportunity queue with impact, effort, evidence, and recommended next actions. |
 |
 |
AI visibility (GEO)
An engines×prompts matrix of where the brand is cited across ChatGPT, Perplexity, Gemini, Claude, and Copilot, with an overall visibility score and trend. |
GEO optimizer
Agent-proposed rewrites that make pages more citable by AI engines, gated by geo-qa — one blocked for a fabricated stat. |
 |
Entity readiness
Entity readiness checklist showing schema coverage, citation signals, and blocked/ready status for AI answer engines. |
## Boundary
- The skill may read the Google Search Console API (read-only scope), normalize search analytics, prepare opportunity drafts, validate schemas, and write local handoff files.
- GSC access is read-only. The skill never mutates Search Console properties, submits sitemaps, or requests indexing without an explicit, separately approved user request.
- The app reads and writes local files only. It must not call the GSC API, edit site content, or mutate remote systems.
- Site-content edits happen only through approved opportunities, executed by the agent OUTSIDE the app (editing the site's repo/CMS), and reported back to `app/.data/execution_report.json`. GEO content changes follow the same rule: approved in `#/optimize`, published by the agent outside the app.
- AI-visibility data is observational: the agent gathers whether engines cite the brand and records it into the snapshot. Never fabricate a citation, an answer position, or a stat — the `geo-qa` gate BLOCKs ungrounded claims for exactly this reason.
- Do not commit `config.local.json`, env files, service-account keys, access tokens, or anything under `app/.data/`.
## First Run And Onboarding
On invocation, check `app/.data/onboarding.json` and private config readiness. If onboarding is absent/incomplete, guide setup before syncing real data.
Private config priority:
1. `KELLY_SEO_CONFIG=/absolute/path/to/config.json`
2. `skills/kelly-seo/config.local.json`
3. `~/.config/kelly-seo/config.json`
4. `skills/kelly-seo/config.example.json` as template only
Env priority:
1. Existing environment variables
2. `KELLY_SEO_ENV_FILE=/absolute/path/to/.env`
3. Repository root `.env`
4. `skills/kelly-seo/.env.local`
5. `~/.config/kelly-seo/.env`
Onboarding asks for non-secret details only: which site properties to track (`property_url`, a short `site_id`, verification type) and which auth method to use. Never ask the user to paste keys or tokens into chat.
Auth methods (choose one):
- Service account (recommended for recurring syncs): the user creates a Google Cloud service account, downloads its JSON key, and adds the service account's email address as a user on each Search Console property (Settings → Users and permissions → Add user, Full or Restricted read access). Point `KELLY_SEO_GSC_SERVICE_ACCOUNT_FILE` at the key file path in a local env file.
- Plain OAuth access token (for quick manual runs): put a short-lived token with scope `https://www.googleapis.com/auth/webmasters.readonly` in `KELLY_SEO_GSC_ACCESS_TOKEN`.
When setup is complete and the user confirms, write `app/.data/onboarding.json`:
```json
{
"completed": true,
"completed_at": "ISO timestamp",
"config_version": "1"
}
```
## Local App
Start the dashboard with:
```bash
skills/kelly-seo/app/start.sh
```
The app uses local HTTP on `127.0.0.1`, preferring port `3000` through `4000`, or `KELLY_SEO_UI_PORT` when set. The launcher reuses a running Kelly SEO server only when `/api/state` proves it is the same app; otherwise it picks the next free port.
Required app views:
- `#/overview`: SEO command desk. Per-site KPI cards (clicks, impressions, CTR, average position, 28d vs previous 28d deltas), a daily clicks/impressions trend, top movers (queries with the biggest click gains and losses), site freshness (last sync), and the human-attention panel for opportunities needing review.
- `#/queries`: top queries table with clicks, impressions, CTR, position, deltas vs the previous period, and opportunity badges such as "position 8-15" or "CTR below expected". Selecting a row opens `#/queries/