Merge pull request #124 from petera2c/small-bug-fixes

Release 4.1.1 with row grouping leaf-row alignment.

Author: petera2c

.agents/skills/competitive-landscape/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: competitive-landscape
+description: Map SEO market leaders, winning content themes, keyword coverage, backlinks, and strategic gaps.
+---
+
+# OpenSEO Competitive Landscape
+
+## Goal
+
+Answer: "Who is winning this SEO market, what content is working for them, and where are the openings?"
+
+Use this when the user wants a market-level view across several competitors. For a deep dive on one domain, use `competitor-analysis`.
+
+## Required inputs
+
+- `projectId`
+- Topic, seed keywords, market/category, or user's domain
+- Optional known competitors
+- Optional location/language
+
+## OpenSEO MCP tools
+
+- `research_keywords`: discover representative market queries.
+- `get_keyword_metrics`: validate known query sets with volume, difficulty, intent, and trends.
+- `get_serp_results`: identify recurring ranking domains across target queries.
+- `find_serp_competitors`: compare domains competing across supplied keywords; use this before manual SERP counting when a keyword set is available.
+- `get_domain_overview`: size organic footprint for candidate leaders.
+- `get_search_console_performance`: when the user's own domain is in the comparison and Search Console is connected, anchor their position with first-party clicks/impressions/CTR rather than third-party estimates.
+- `get_ranked_keywords`: find exact ranking keywords, URLs, ranks, intents, and SERP result types for leaders.
+- `get_backlinks_overview`: compare backlink/referring-domain strength where relevant.
+- `search_local_businesses`, `get_local_serp_results`, and `get_google_business_questions`: use for local SEO markets where proximity, Maps rankings, business categories, reviews, or Google Q&A affect who is winning.
+
+## Workflow
+
+1. Define the market query set:
+   - Use provided keywords, or call `research_keywords` to build 5-10 representative queries.
+   - Include mixed intent: informational, commercial, comparison, and tool/software terms when applicable.
+   - For local SEO, include neighborhood/city/service-area queries and identify the priority locations or coordinates.
+2. If the query set is already known, use `get_keyword_metrics` to validate relative demand and difficulty and `find_serp_competitors` to identify recurring domains at scale.
+3. For local SEO, call `search_local_businesses` and `get_local_serp_results` for the highest-priority location(s) before synthesizing winners. Use `get_serp_results` as a complement for organic pages, not as the only local evidence.
+4. Call `get_serp_results` for representative queries when live SERP composition, ranking URLs, or SERP features need inspection. Send at most 10 queries per call.
+5. Identify recurring domains and group them by type:
+   - Direct product competitors
+   - Publishers/media
+   - Marketplaces/directories
+   - Communities/forums
+   - Documentation/resources
+6. For the strongest recurring domains, call `get_domain_overview`; default to the top 3-5 domains before expanding.
+7. For direct competitors and relevant publishers, call `get_ranked_keywords`.
+8. Use `get_backlinks_overview` when backlink authority appears important or the user asks why a domain is winning. Backlinks may be unavailable if the account has not enabled that data; continue with SERP/domain evidence if it fails.
+9. Synthesize patterns: content types, themes, SERP formats, local-pack signals, authority advantages, and underserved angles.
+
+## Output format
+
+Start with the market read:
+
+- Market leaders
+- Most winnable opportunity area
+- Biggest barrier to ranking
+
+Then include:
+
+| Domain | Type | Why they matter | Organic footprint | Winning themes | Weakness/gap |
+| ------ | ---- | --------------- | ----------------- | -------------- | ------------ |
+
+Add:
+
+- Query set used
+- Content formats that are working
+- Keyword/theme gaps
+- Backlink or authority observations
+- Recommended next workflows: competitor analysis, keyword clustering, or content brief
+
+## Guardrails
+
+- Distinguish SEO competitors from business competitors.
+- Do not overstate exact traffic when OpenSEO returns estimates.
+- If using a small query set, call the result directional.
+- Do not assume a publisher is a product competitor; label domain types clearly.
+- For local markets, distinguish organic-page winners from Maps/local-pack winners.

.agents/skills/competitor-analysis/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: competitor-analysis
+description: "Analyze one competitor's organic footprint, ranking keywords, content themes, backlinks, and gaps."
+---
+
+# OpenSEO Competitor Analysis
+
+## Goal
+
+Analyze one competitor deeply enough to decide what to learn from, avoid, counter-position against, or outrank.
+
+Use this for a named competitor. For identifying the market leaders first, use `competitive-landscape`.
+
+## Required inputs
+
+- `projectId`
+- Competitor domain
+- User's domain when comparison is requested
+- Optional topic/category/location/language
+
+## OpenSEO MCP tools
+
+- `get_domain_overview`: baseline organic traffic and keyword count.
+- `get_search_console_performance`: when comparing to the user's own domain and Search Console is connected, use it as the first-party baseline (real clicks/impressions/CTR/position) instead of estimating the user's own performance from third-party data.
+- `get_ranked_keywords`: exact keyword, URL, rank, intent, traffic, CPC, and SERP-type rows for the competitor domain or page.
+- `get_backlinks_overview`: backlink/referring-domain profile.
+- `find_serp_competitors`: validate whether the named competitor is a real search competitor across the target keyword set.
+- `search_local_businesses`, `get_local_serp_results`, and `get_google_business_questions`: use for local SEO competitors when Maps/local-pack visibility, nearby businesses, categories, or Google Q&A matter.
+- `get_serp_results`: validate direct head-to-head SERPs for important keywords.
+- `research_keywords`: expand gaps or category terms when needed.
+
+## Workflow
+
+1. Call `get_domain_overview` for the competitor, passing provided location/language when supported.
+2. If comparing to the user, call `get_domain_overview` for the user's domain too — and if Search Console is connected, `get_search_console_performance` for the user's real baseline.
+3. Call `get_ranked_keywords` for the competitor. Use filters like `maxRank`, `minSearchVolume`, `excludeBrandTerms`, and `resultTypes` to keep rows relevant.
+4. If comparing to the user, call `get_ranked_keywords` for the user's domain/page too, or use `get_serp_results` for the shared terms when a lighter check is enough.
+5. For local SEO, use `search_local_businesses` and `get_local_serp_results` around the relevant business location(s) before drawing local-pack conclusions. Add `get_google_business_questions` only when Q&A evidence matters.
+6. Use `find_serp_competitors` when the competitor was supplied by the user but its search overlap is unclear.
+7. Group competitor keywords into themes:
+   - Product/category terms
+   - Alternatives/comparisons
+   - Templates/tools/calculators
+   - Educational guides
+   - Branded demand
+   - Local/neighborhood terms when relevant
+8. Call `get_backlinks_overview` for the competitor, especially if authority appears to explain rankings. Continue without backlink evidence if it is unavailable.
+9. Use `get_serp_results` for important shared or target keywords to compare positioning, passing provided location/language when supported.
+10. Produce an actionable plan:
+    - What they are doing well
+    - Where they are vulnerable
+    - Which pages/keywords to pursue
+    - What to avoid copying
+
+## Output format
+
+Start with:
+
+- Competitor snapshot
+- Biggest lesson
+- Best opportunity to beat them
+
+Then include:
+
+| Area | Competitor pattern | Evidence | OpenSEO opportunity |
+| ---- | ------------------ | -------- | ------------------- |
+
+Include sections for:
+
+- Top keyword themes
+- Content/page types working for them
+- Backlink/authority notes
+- Head-to-head SERP observations
+- Priority actions for the user
+
+## Guardrails
+
+- Do not treat all competitor keywords as desirable. Filter for business fit.
+- Separate evidence from inference.
+- Do not infer competitor page/content-type patterns from keyword rows alone; use SERP or web evidence for page-level claims.
+- For local SEO, do not infer Maps/local-pack strength from national organic domain metrics alone; use local business and local SERP tools when the location is known or reasonably discoverable.
+- Do not recommend copying content; recommend a stronger angle or better answer to the same intent.
+- If the user's domain is unavailable, frame the analysis as competitor-only.

.agents/skills/keyword-clustering/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: keyword-clustering
+description: Cluster keywords by intent and map them to existing or proposed pages.
+---
+
+# OpenSEO Keyword Clustering
+
+## Goal
+
+Group keywords into page-level clusters and decide which existing or new page should target each cluster. This is a keyword mapping workflow, not just a semantic grouping exercise.
+
+## Required inputs
+
+- `projectId`
+- A keyword list, saved keyword tag, seed topic, or target domain
+- Optional existing URLs/pages to map against
+
+If keywords are not provided, use `list_saved_keywords` for saved sets, `research_keywords` for seed discovery, or `get_ranked_keywords` when the user starts from a target domain.
+
+## OpenSEO MCP tools
+
+- `list_saved_keywords`: fetch an existing keyword set, optionally filtered by tags.
+- `research_keywords`: expand a seed when the user starts from a topic.
+- `get_ranked_keywords`: gather exact ranking keywords and URLs when the user starts from a domain or page.
+- `get_search_console_performance`: when Search Console is connected, pull real queries with `dimensions: ["query","page"]` to map terms to the pages already earning impressions and to surface cannibalization (one query splitting clicks across multiple URLs).
+- `get_serp_results`: validate whether keywords belong on the same page by checking SERP overlap and intent.
+- `get_local_serp_results`: use for local SEO clusters when Maps/local-pack intent should affect page mapping.
+- `save_keywords`: optionally tag final clusters after user confirmation.
+
+## Workflow
+
+1. Gather the candidate keyword set.
+   - Use `get_search_console_performance` (dimensions `["query","page"]`) when Search Console is connected to start from real queries and the pages already ranking for them.
+   - Use `get_ranked_keywords` for domain/page-driven clustering.
+   - Use `search_local_businesses` and `get_local_serp_results` when proximity, local packs, or Google Business results determine whether terms belong on location pages.
+2. Remove duplicates, irrelevant terms, and terms that clearly require a different product or audience.
+3. Build clusters around intent and page type:
+   - Same SERP intent and similar ranking pages belong together.
+   - Different intent, buyer stage, or SERP format should be split.
+   - Similar words do not guarantee the same cluster.
+4. For important borderline terms, use a small `get_serp_results` batch to check overlap.
+5. Assign each cluster to:
+   - Existing URL, if supplied and appropriate
+   - New page recommendation, if no existing page fits
+   - Do-not-target / later bucket, if weak or off-strategy
+6. Identify cannibalization risk when multiple pages would target the same intent. When Search Console is connected, confirm it from real data with `get_search_console_performance` (`dimensions: ["query","page"]`) — the same query sending impressions to multiple URLs.
+7. Ask before applying cluster tags with `save_keywords`.
+
+## Output format
+
+Start with a short mapping summary:
+
+- Number of clusters
+- Pages to create
+- Existing pages to update
+- Cannibalization or consolidation issues
+
+Then include:
+
+| Cluster | Primary keyword | Secondary keywords | Intent | Target page | Priority | Notes |
+| ------- | --------------- | ------------------ | ------ | ----------- | -------- | ----- |
+
+For each cluster, include a recommended page brief:
+
+- Page type
+- Searcher problem
+- Required sections
+- Internal-link opportunities
+- Save/tag suggestion
+
+## Guardrails
+
+- Do not over-cluster tiny keyword sets. If there are fewer than 10 usable terms, produce a simple map.
+- Do not rely on lexical similarity alone. SERP intent wins.
+- Do not replace tags broadly without explicit confirmation.
+- If existing URL data is missing, label target pages as proposed.

.agents/skills/keyword-research/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: keyword-research
+description: "Discover keyword opportunities, evaluate metrics and SERPs, and save/tag promising terms."
+---
+
+# OpenSEO Keyword Research
+
+## Goal
+
+Turn seed topics into a prioritized keyword opportunity set using OpenSEO MCP data. The output should help the user decide what to target, what to save, and what to research next.
+
+## Required inputs
+
+- `projectId`
+- One or more seed topics, products, pages, competitors, or audience problems
+- Optional market/location/language
+
+If `projectId` is missing, use `list_projects` first. If the target market/location/language is unclear and would materially affect keyword metrics, ask the user; otherwise use the MCP tool defaults.
+
+## OpenSEO MCP tools
+
+- `research_keywords`: primary discovery tool. Use 1-5 seeds per call and prefer 150 results unless the user asks for exhaustive research.
+- `get_keyword_metrics`: hydrate up to 700 known keywords with volume, keyword difficulty (KD), search intent, CPC, and monthly trends in one call. Use it to score candidate or known terms — including the Search Console striking-distance queries from step 1.
+- `get_ranked_keywords`: pull exact ranking keyword rows when a target domain or page is part of the research brief.
+- `get_search_console_performance`: when Search Console is connected, start from the project's real first-party demand — queries already earning impressions and near-ranking ("striking distance") terms. Request a high `rowLimit` and filter average position 5-20 client-side, since the API sorts by clicks and can't filter by position. Then hydrate those striking-distance queries with `get_keyword_metrics` to attach difficulty and intent.
+- `get_serp_results`: inspect SERPs for the top candidate terms, especially when intent is ambiguous.
+- `search_local_businesses`, `get_local_serp_results`, and `get_google_business_questions`: use for local SEO topics when a business/location radius matters.
+- `list_saved_keywords`: avoid duplicating already-saved work or use existing tags as context.
+- `save_keywords`: save selected keywords only after explicit user confirmation.
+
+## Workflow
+
+1. Normalize seeds into a small set of distinct research angles. If Search Console is connected for the project, first pull `get_search_console_performance` (high `rowLimit`, default lookback), filter to striking-distance positions (~5–20) client-side, and hydrate those queries with `get_keyword_metrics` to attach KD and intent. That ranked, hydrated list is your fastest opportunity set — work it before broad discovery.
+2. If the request is local SEO, identify the business, location/coordinates or service area, and local categories. Use `search_local_businesses` and `get_local_serp_results` for the most important location/keyword set instead of relying only on national keyword/SERP data.
+3. Call `research_keywords` for exploratory seeds. Use bulk calls when possible.
+4. Use `get_keyword_metrics` to hydrate a fixed keyword list — or the striking-distance queries from step 1 — with volume, KD, and intent before prioritizing.
+5. Use `get_ranked_keywords` when the user provides a domain/page and wants opportunities based on current rankings, near-misses, or competitor-owned terms.
+6. Remove irrelevant, duplicate, branded-only, and off-intent terms.
+7. Prioritize by practical opportunity, not volume alone:
+   - Strong match to the user's product/page/topic
+   - Clear search intent
+   - Reasonable difficulty
+   - Useful volume/CPC signal
+   - SERP where the user can plausibly compete
+   - For local SEO, local-pack/Maps visibility and proximity fit
+8. Use `get_serp_results` for high-potential or ambiguous keywords when SERP intent would change the recommendation; keep the default check small.
+9. Present a shortlist and a longer opportunity table.
+10. Ask before saving keywords. When saving, suggest concise tags such as `topic:<topic>`, `intent:<intent>`, or `page:<slug>`.
+
+## Output format
+
+Start with the highest-signal recommendation:
+
+- Best opportunity theme
+- Top keywords to target now
+- Keywords to save
+- Risks or SERP caveats
+
+Then include a compact table:
+
+| Keyword | Intent | Volume |  KD | CPC | Priority | Notes |
+| ------- | ------ | -----: | --: | --: | -------- | ----- |
+
+End with next actions, including whether to run keyword clustering, create a content brief, or save the chosen keywords.
+
+## Guardrails
+
+- Do not invent metrics. If OpenSEO does not return a value, write `unknown`.
+- Do not call `save_keywords` without explicit confirmation.
+- Prefer business-fit and intent-fit over chasing the largest volume term.