git:20260711.c9add96 to git:20260806.bed1b85

- description: Personal App-in-Skill desk covering SEO + GEO (AI-search) + brand entity — wired to Google Search Console for a local dashboard over search analytics and an agent-prepared SEO opportunities review queue, plus an AI-visibility tracker (are we cited in ChatGPT / Perplexity / Gemini / Claude / Copilot answers), a GEO content-optimization queue gated by geo-qa, and an entity / knowledge-panel readiness checklist. Use when the user invokes $kelly-seo or /kelly-seo, mentions SEO, Google Search Console, GSC, search analytics, search performance, queries, keywords, rankings, positions, impressions, clicks, CTR, striking-distance queries, title/meta rewrites, content briefs, internal links, SEO opportunities review, GEO, generative engine optimization, AI search, AI visibility, being cited by AI answer engines, ChatGPT/Perplexity/Gemini/Claude/Copilot citations, brand entity, knowledge panel, Wikidata, schema.org, or entity readiness.

- Use this skill as Kelly's local SEO + GEO desk. It pulls Google Search Console search analytics (clicks, impressions, CTR, position for queries and pages across configured site properties) into one file-backed App-in-Skill dashboard, and runs an agent-prepared SEO opportunities review queue: title/meta rewrites, internal-link suggestions, new-content briefs, and page-issue fixes that the user approves, edits, or blocks.

- It also covers the AI-search side (GEO — Generative Engine Optimization): an AI-visibility tracker showing whether AI answer engines (ChatGPT / Perplexity / Gemini / Claude / Copilot) cite the brand for a set of tracked prompts, a GEO content-optimization review queue (agent-drafted rewrites that make a page more citable, each scored by the `geo-qa` quality gate), and a brand-entity / knowledge-panel readiness checklist (Wikidata, schema.org Organization/Person, consistent NAP, sameAs links). GEO opportunities and entity signals flow through the same data-provider layer and the same five-state review model as SEO opportunities.

- Default interaction mode: App UI. Unless the user explicitly asks for chat-only handling, check onboarding/config, refresh or load the local SEO snapshot, start/reuse the local app with `app/start.sh`, and give the actual local URL. Use chat-only mode only when the user says "纯聊天", "chat only", "不要打开 UI", or similar.

- - 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/`.

- 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:

- 4. `skills/kelly-seo/config.example.json` as template only

- 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.

- When setup is complete and the user confirms, write `app/.data/onboarding.json`:

-

- ```json

- {

- "completed": true,

- "completed_at": "ISO timestamp",

- "config_version": "1"

- }

- ```

-

- 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:

- - `#/opportunities`: review queue with workflow states `needs_review`, `changes_requested`, `approved`, `done`, and `blocked`. Each agent-proposed action (title/meta rewrite with draft, internal-link suggestion, new-content brief, fix-page issue) carries a reason, expected impact, an editable draft, decision buttons (approve / request changes / block), a `Review note` textarea, and a stable reference such as `Opportunity #1`.

- - `#/optimize`: GEO content-optimization review queue with the same `needs_review / changes_requested / approved / done / blocked` states. Each agent-proposed change (citable rewrite, quotable stats, Q&A block, schema markup) carries a target prompt, reason, expected impact, an editable draft, kb-style grounding lines, and a `geo-qa` gate verdict (SHIP / FIX / BLOCK). A change the gate BLOCKs (for example a fabricated stat) cannot be approved until the failing checks are resolved.

- - `#/settings`: sanitized config only: sites, auth method plus env readiness booleans (never key contents), data provider, and onboarding state.

- - `?demo=1` opens a deterministic mock SEO desk for documentation and screenshots.

- - Demo API responses must never read or write live GSC data or files under `app/.data/`. Demo decisions stay in the browser only.

- ## File Contract

-

- Read `references/seo-schema.md` before editing the app, scripts, or any generated SEO JSON.

-

- Primary local files:

-

- - `app/.data/seo_snapshot.json`: canonical dashboard snapshot (sites, daily series, queries, pages, opportunities, metrics) generated by the skill/scripts.

- - `app/.data/decisions.json`: user verdicts and notes keyed by opportunity id.

- - `app/.data/geo_decisions.json`: user verdicts on GEO content-optimization opportunities, keyed by GEO opportunity id.

- - `app/.data/entity_signals.json`: user overrides for entity-readiness signals (status + note), keyed by signal id.

- - `app/.data/agent_tasks.json`: queued agent work — opportunities in `changes_requested` with the user's revision note.

- - `app/.data/execution_report.json`: latest execution results for approved opportunities.

- - `app/.data/onboarding.json`: onboarding completion marker.

- - `app/.data/agent.lock`: temporary lock while the skill is syncing, regenerating opportunities, or executing. The app rejects decision writes while the lock exists.

- - `config.local.json`: private site/auth configuration, ignored by git.

-

- Use `scripts/validate_ui_schema.ts app/.data/seo_snapshot.json` before relying on a snapshot in the UI. The app may show an empty setup state when no snapshot exists.

-

- 1. Detect mode. Default to App UI.

- 2. Load private config. If only `config.example.json` exists, enter onboarding.

- 4. Acquire `app/.data/agent.lock`, run `scripts/sync_gsc.ts`, and release the lock. The script pulls Search Analytics dimensioned by query, by page, and by date for both windows, normalizes into the snapshot, computes deltas and opportunity badges, and preserves the existing `opportunities[]` batch.

- 5. Validate with `scripts/validate_ui_schema.ts`, start/reuse the UI, and report the URL.

- 6. GSC data lags about two days; the sync window ends two days before today. Surface API errors and missing-property warnings in the snapshot `warnings[]`, never as silent failures.

- `scripts/sync_gsc.ts` fails gracefully with setup guidance when neither `KELLY_SEO_GSC_SERVICE_ACCOUNT_FILE` nor `KELLY_SEO_GSC_ACCESS_TOKEN` is usable. It is never required for demo mode or app startup.

- 1. After a sync, analyze the snapshot for striking-distance queries (position 8-15), CTR below the expected curve for the position, pages losing clicks, internal-link gaps, and page issues. Write proposed actions into `seo_snapshot.json` `opportunities[]` with stable ids, sequential `ref` numbers, a reason, an expected impact, and an editable draft.

- 2. Send the user to `#/opportunities` to review. The user approves, edits drafts, requests changes with a note, or blocks.

- 3. Poll `app/.data/agent_tasks.json` for `changes_requested` items, revise the draft per the note, and return the item to `needs_review`.

- 4. On explicit user request to execute, run `scripts/execute_decisions.ts` (dry-run by default). It re-checks the lock and decisions and writes `execution_report.json` entries with concrete operations (`rewrite_title`, `add_internal_links`, `create_content_brief`, `fix_page_issue`) and target page/query — no external side effects.

- 5. The agent then performs the approved edits in the site's repo/CMS outside the app, records real results in `execution_report.json`, and marks executed opportunities `done` in the snapshot.

- 1. GEO state lives in the same `seo_snapshot.json` under `ai_visibility` (tracked prompts × engines with position + sentiment + trend), `geo_opportunities` (agent-proposed citable rewrites), and `entity_signals` (the readiness checklist). Route all reads/writes through the data-provider layer — never bypass it with raw `node:fs`.

- 2. For each agent-proposed GEO change, run the `geo-qa` gate (`lib/geo-qa.ts`) over the draft. It returns SHIP / FIX / BLOCK with a GEO Quality Score and per-check notes. The primary failure is an ungrounded/fabricated stat — a number in the copy with no cited source. A BLOCK is a hard gate: the app rejects an approve (HTTP 422) until the change is fixed.

- 3. Send the user to `#/optimize` to review. Approvals are written to `app/.data/geo_decisions.json`; the app writes local files only. Execution semantics: `operation: publish_geo_change, page, draft_id` — the agent publishes the approved citable content in the site's repo/CMS OUTSIDE the app, then records the real result and marks the item `done`.

- 4. Entity-readiness edits from `#/entity` are written to `app/.data/entity_signals.json` with `operation: update_entity_signal`. The agent then earns the real signal (create the Wikidata item, add the sameAs links, standardize the brand name) outside the app.

- - Prefer the read-only GSC scope; never store key file contents or tokens in the snapshot, logs, UI state, or reports — expose only env readiness booleans.

- - Keep local data minimal: top queries/pages and aggregates, not raw exports beyond what the dashboard needs.

- - If GSC totals and per-dimension rows disagree (sampling/privacy filtering), do not invent corrections; add a snapshot warning explaining the gap.