luckiest-co 1.0.47 → 1.0.49

package/skills/schema/evals/evals.json

@@ -83,6 +83,46 @@
         "Does not attempt full SEO audit using schema markup patterns"
       ],
       "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "Our Next.js product page embeds JSON-LD with dangerouslySetInnerHTML and JSON.stringify(schema). Product names come from a CMS and can contain HTML, quotes, ampersands and Unicode. How do we keep product text intact without allowing it to terminate the JSON-LD script element?",
+      "expected_output": "Should use the schema implementation example and escape the serialized JSON for its HTML script context by replacing every less-than character with a literal JSON Unicode escape before assigning __html. Should explain that JSON.stringify alone does not protect the HTML parser boundary, preserve the original product text when JSON is parsed, and avoid deleting content, HTML-entity escaping JSON or directly interpolating raw names. Should refer to the current official Next.js guidance.",
+      "assertions": [
+        "Identifies the script element HTML parsing boundary",
+        "Escapes every less-than character after JSON serialization",
+        "Preserves original product text after JSON.parse",
+        "Does not treat JSON.stringify alone as safe HTML embedding",
+        "Uses the linked Next.js guidance"
+      ],
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "It's October 2026. Our product FAQ has 20 questions. Add FAQ schema so Google shows expandable questions in our search result, and tell us how to validate that feature.",
+      "expected_output": "Should explain before offering implementation that Google stopped showing FAQ rich results in May 2026, citing Google's current documentation updates. The earlier government/health exception does not apply now. Should separate Schema.org vocabulary validity from Google feature eligibility. If semantic FAQPage markup is still wanted for another consumer, ask for the actual visible questions and answers and use mainEntity > Question > acceptedAnswer; don't invent product answers. Recommend Schema.org Validator for vocabulary. Missing FAQ detection or reports in Rich Results Test or Search Console is not an implementation defect. Do not promise expandable results or tell the user to delete unrelated supported markup.",
+      "assertions": [
+        "Explains Google FAQ rich results were retired before proposing code",
+        "Cites current official Google feature guidance",
+        "Does not present the old government/health exception as current eligibility",
+        "Separates Schema.org validity from Google feature eligibility",
+        "Offers semantic markup only with a separate purpose and actual visible content",
+        "Does not treat missing retired-feature detection/reporting as a defect",
+        "Does not promise the requested retired search appearance"
+      ],
+      "files": []
+    },
+    {
+      "id": 9,
+      "prompt": "Our tutorial uses valid HowTo JSON-LD but the Rich Results Test does not detect it. Should we fix the syntax until Google shows tutorial steps? Also, our homepage lost its sitelinks search box; should we delete all WebSite markup?",
+      "expected_output": "Should check current feature support and explain Google's HowTo and sitelinks search box retirements with official references. Valid vocabulary cannot restore those appearances. Use Schema.org Validator if there is a semantic consumer; do not diagnose missing retired-feature detection as a syntax failure. Preserve useful WebSite site-name markup and unrelated supported features. Separate remaining syntax/content issues from feature availability.",
+      "assertions": [
+        "Recognizes retired HowTo and sitelinks search box features",
+        "Separates syntax errors from unavailable appearances",
+        "Keeps WebSite site identity and unrelated supported markup",
+        "Uses official feature-support sources and appropriate validators"
+      ],
+      "files": []
     }
   ]
 }

package/skills/schema/references/schema-examples.md

@@ -4,7 +4,7 @@ Complete JSON-LD examples for common schema types.
 
 ## Contents
 - Organization
-- WebSite (with SearchAction)
+- WebSite (site identity)
 - Article / BlogPosting
 - Product
 - SoftwareApplication
@@ -42,24 +42,16 @@ For company/brand homepage or about page.
 
 ---
 
-## WebSite (with SearchAction)
+## WebSite (site identity)
 
-For homepage, enables sitelinks search box.
+For homepage/site identity. Google retired the sitelinks search box in November 2024; adding `SearchAction` cannot restore it. Keep useful `WebSite` markup for site names. See the [search box announcement](https://developers.google.com/search/blog/2024/10/sitelinks-search-box).
 
 ```json
 {
   "@context": "https://schema.org",
   "@type": "WebSite",
   "name": "Example",
-  "url": "https://example.com",
-  "potentialAction": {
-    "@type": "SearchAction",
-    "target": {
-      "@type": "EntryPoint",
-      "urlTemplate": "https://example.com/search?q={search_term_string}"
-    },
-    "query-input": "required name=search_term_string"
-  }
+  "url": "https://example.com"
 }
 ```
 
@@ -162,7 +154,7 @@ For SaaS product pages and app landing pages.
 
 ## FAQPage
 
-For pages with frequently asked questions.
+For visible frequently asked questions when a consumer needs Schema.org semantics. Google FAQ rich results were retired in May 2026; this example cannot enable expandable Google search results. Use the Schema.org Validator for vocabulary validation, not missing Rich Results Test detection as a failure. See [Google's documentation updates](https://developers.google.com/search/updates).
 
 ```json
 {
@@ -193,7 +185,7 @@ For pages with frequently asked questions.
 
 ## HowTo
 
-For instructional content and tutorials.
+For instructional content and tutorials when a consumer needs Schema.org semantics. Google retired HowTo rich results in September 2023; this example does not restore that appearance. See the [retirement announcement](https://developers.google.com/search/blog/2023/08/howto-faq-changes).
 
 ```json
 {
@@ -388,7 +380,7 @@ export default function ProductPage({ product }) {
       <Head>
         <script
           type="application/ld+json"
-          dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(schema).replace(/</g, '\\u003c') }}
         />
       </Head>
       {/* Page content */}
@@ -396,3 +388,5 @@ export default function ProductPage({ product }) {
   );
 }
 ```
+
+When JSON-LD is inserted as raw HTML, JSON escaping alone does not stop a product string containing a script-closing tag from terminating the element. Escape every `<` in the serialized JSON as `\u003c`, as in the example above; parsing the JSON recovers the original product text. Do this at the HTML embedding boundary, without deleting legitimate characters from the source data. See the [Next.js JSON-LD guide](https://nextjs.org/docs/app/guides/json-ld).

package/skills/seo-audit/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog — luckiest-seo-audit
 
+## 1.2.0 — 2026-10-16
+From coreyhaines31/marketingskills at 1efedbc (issue #174, MIT).
+
+- New references: title tags, rankings push (striking-distance keywords), local SEO (profile, citations, pages and measurement).
+
 ## 1.1.0 — 2026-07-06
 Skill updater pass: analytics integration.
 

package/skills/seo-audit/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: seo-audit
-description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see luckiest-programmatic-seo. For adding structured data, see luckiest-schema. For AI search optimization, see luckiest-ai-seo.
+description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," "indexing issues," "stuck on page 2," "striking distance keywords," "title tag rewrite," "low CTR," "local SEO," "Google Business Profile," or "map pack." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see luckiest-programmatic-seo. For adding structured data, see luckiest-schema. For AI search optimization, see luckiest-ai-seo.
 license: See ATTRIBUTION.md
 metadata:
-  version: "1.1.0"
+  version: "1.2.0"
   listing_id: luckiest-seo-audit
   author: luckiest
 ---
@@ -14,9 +14,9 @@ This skill helps identify SEO issues and provide actionable recommendations to i
 
 ## Staying current
 
-On activation, call the Luckiest MCP check_updates tool with { listingId: "eb3e5efe-31ff-46bc-9aea-0df6bb2afc36", installedSemver: "1.1.0" }. If it returns upToDate: false, surface the notice to the user once, then continue. Do nothing further if upToDate: true. Never block on this check — if the tool is unavailable, proceed.
+On activation, call the Luckiest MCP check_updates tool with { listingId: "eb3e5efe-31ff-46bc-9aea-0df6bb2afc36", installedSemver: "1.2.0" }. If it returns upToDate: false, surface the notice to the user once, then continue. Do nothing further if upToDate: true. Never block on this check — if the tool is unavailable, proceed.
 
-When the skill's work is done, call the Luckiest MCP report_usage tool once with { listing_id: "luckiest-seo-audit", skill_version: "1.1.0", matched: true, success: <true if the skill completed, false otherwise> }. Metadata only, never prompt text. Never block on it — if the tool is unavailable, skip silently.
+When the skill's work is done, call the Luckiest MCP report_usage tool once with { listing_id: "luckiest-seo-audit", skill_version: "1.2.0", matched: true, success: <true if the skill completed, false otherwise> }. Metadata only, never prompt text. Never block on it — if the tool is unavailable, skip silently.
 
 ## Initial Assessment
 
@@ -76,6 +76,8 @@ The same blind spot that hides JS-injected schema also hides primary content and
 4. **Content Quality** (does it deserve to rank?)
 5. **Authority & Links** (does it have credibility?)
 
+Once the foundations are sound, the fastest wins are usually pages already ranking in positions 8–20. See [rankings-push.md](references/rankings-push.md) for that workflow and the checklist for shipping new pages.
+
 ---
 
 ## Technical SEO Audit
@@ -259,19 +261,9 @@ Three equivalent placement methods: HTML `<link>` in `<head>`, HTTP `Link` heade
 
 ### Title Tags
 
-**Check for:**
-- Unique titles for each page
-- Primary keyword near beginning
-- 50-60 characters (visible in SERP)
-- Compelling and click-worthy
-- Brand name placement (end, usually)
+**Check for:** unique titles, primary query near the front, about 50–60 characters, a reason to click, alignment with the H1, and a pattern that fits the page type.
 
-**Common issues:**
-- Duplicate titles
-- Too long (truncated)
-- Too short (wasted opportunity)
-- Keyword stuffing
-- Missing entirely
+**Common issues:** duplicates, truncation, keyword stuffing, missing titles, and titles Google rewrites in results. Patterns by page type, the rewrite triggers, and a bulk-audit format are in [title-tags.md](references/title-tags.md).
 
 ### Meta Descriptions
 
@@ -442,6 +434,8 @@ Three equivalent placement methods: HTML `<link>` in `<head>`, HTTP `Link` heade
 - Missing location pages
 - No local content
 
+For Google Business Profiles, the map pack, citations, reviews, and location pages, see [local-seo.md](references/local-seo.md).
+
 ---
 
 ## Output Format

package/skills/seo-audit/evals/evals.json

@@ -131,6 +131,74 @@
         "May briefly mention FAQ schema benefits"
       ],
       "files": []
+    },
+    {
+      "id": 9,
+      "prompt": "Search Console shows a bunch of our pages sitting at positions 9 to 15, and our pricing page ranks #3 but barely gets clicks. Where do we start?",
+      "expected_output": "Should load the rankings push reference. Should bucket candidates: striking distance (positions 8-20 above an impression floor) for content and link fixes, and weak click-through at a top-5 position for title and meta description fixes only. Should prioritize by business value, check for cannibalization first, diagnose each page against the top three results (intent, missing section, freshness, format, links), and make the smallest change that closes the gap, including answering the query in the first two sentences and adding internal links from strong pages. For the pricing page, should rewrite only the title and meta description using the pricing pattern from the title-tags reference. Should record baselines, wait 3-4 weeks before judging, and stop after two rounds with no movement.",
+      "assertions": [
+        "Separates striking-distance pages from the weak-CTR pricing page",
+        "For the pricing page, changes only title and meta description",
+        "Checks for cannibalization before editing",
+        "Diagnoses against the top three results with a concrete reason",
+        "Recommends internal links from strong related pages",
+        "Records baselines and waits 3-4 weeks before judging",
+        "Does not recommend repeatedly resubmitting URLs in Search Console"
+      ],
+      "files": []
+    },
+    {
+      "id": 10,
+      "prompt": "Our example.de/ and example.com/de/ pages contain equivalent German content for two regions. The audit says every locale must self-canonicalize and cross-locale canonicals always conflict with hreflang. Must we keep both self-canonicals? Our separate French translation and page-two pagination also need review.",
+      "expected_output": "Reject the blanket rule. For similar or duplicate same-language regional content, consider a preferred canonical with consistent hreflang using current Google guidance. Preserve distinct French translation and per-page pagination strategies; do not consolidate different languages merely because the product matches. Check actual content and signals and avoid promising all regional URLs will stay indexed.",
+      "assertions": [
+        "Distinguishes same-language regional duplicates from distinct translations",
+        "Allows a preferred canonical for same-language duplicates",
+        "Keeps canonical and hreflang signals consistent",
+        "Preserves distinct-language and pagination controls",
+        "Does not guarantee independent indexing"
+      ],
+      "files": []
+    },
+    {
+      "id": 11,
+      "prompt": "I am a mobile locksmith based at my house in Denver. Customers never visit me. I cover Denver and Aurora and want three profiles to rank everywhere. My old citation has the wrong phone. Also write a review request offering $10 off for five stars, and local schema. Give me a practical plan.",
+      "expected_output": "Diagnoses one actual service-area base, hides the private address, corrects the wrong phone, replaces an incentivized/rating-directed request with a neutral honest request, and avoids invented branches or an address in public markup. Explains Google rich-result address requirements without claiming areaServed substitutes or guaranteed map rankings.",
+      "assertions": [
+        "Distinguishes service coverage from additional eligible locations",
+        "Keeps private home address out of public citations and markup",
+        "Corrects observed wrong phone before growing listings",
+        "Provides an honest review request without incentive or five-star requirement",
+        "Does not promise Google rich-result eligibility without a public address",
+        "Explains searcher distance and avoids ranking guarantees"
+      ],
+      "files": []
+    },
+    {
+      "id": 12,
+      "prompt": "Write a Google Business Profile description for Harbor Cycle, our staffed bike shop in Bristol. We sell commuter bikes and do same-day puncture repairs when capacity allows. Open Tuesday to Saturday, 10–6. Keep this focused on the description.",
+      "expected_output": "Produces a factual concise description using supplied facts. Does not add unsupported superlatives, promotions, links, or require a full audit. Keeps conditional same-day availability accurate.",
+      "assertions": [
+        "Delivers requested description directly",
+        "Preserves capacity condition for same-day repairs",
+        "No invented prices, promotions, reviews, links, or unsupported superiority claims",
+        "Does not require unrelated analytics or a complete audit"
+      ],
+      "files": []
+    },
+    {
+      "id": 13,
+      "prompt": "We have two staffed dental practices. One moved last month and has an old profile address; the other is correct. Make a local SEO recovery plan. A crawler text export has no JSON-LD; can you say schema is missing? We also want to seed 20 profile Q&A through the API.",
+      "expected_output": "Treats the move as a location identity/update task, preserves the other real branch, requests specific profile and website evidence, refuses to infer absence of rendered JSON-LD from stripped text, and explains that the old Q&A API is discontinued. Gives a prioritized location-specific plan and measured outcomes without assuming suspension or promising recovery speed.",
+      "assertions": [
+        "Maintains two distinct actual practices",
+        "Prioritizes old-address correction for moved location",
+        "Labels unknown profile status and asks for relevant evidence",
+        "Does not infer absent schema from a stripped text export",
+        "Does not propose discontinued Q&A API calls",
+        "Links follow-up to correct contact paths and qualified bookings"
+      ],
+      "files": []
     }
   ]
 }

package/skills/seo-audit/references/international-seo.md

@@ -64,30 +64,28 @@ For both engines: implement hreflang (Google/Yandex) + `<html lang="...">` + `<m
 
 ## Canonicalization & i18n
 
-### Self-Referencing Canonicals
+### Choose Canonicals by Content and Language
 
-Each locale page must canonical to itself. John Mueller: "Don't use a rel=canonical across languages/countries, only use it on a per-country/language basis."
+Use self-referencing canonicals for distinct locale pages, including genuinely translated content. Do not consolidate different-language translations merely because they describe the same product.
 
-Google's docs: "Specify a canonical page in the same language, or the best possible substitute language if a canonical doesn't exist for the same language."
+For similar or duplicate regional pages in the **same language**, Google recommends choosing a preferred canonical and using consistent `hreflang` annotations. For example, equivalent German content at `example.de/` and `example.com/de/` can share a preferred canonical; every regional URL is not required to canonicalize to itself.
 
-- [John Mueller: hreflang canonical](https://johnmu.com/hreflang-canonical/)
+- [Google: Handling duplicate multilingual/multi-regional pages](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites#handling-duplicate-pages-with-multilingualmulti-regional-sites)
 - [Google: Consolidate Duplicate URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)
 
-### Canonical Overrides Hreflang
+### Align Canonical and Hreflang Signals
 
-Mueller: "If your canonical is pointing somewhere else, Google will follow that and ignore your hreflang annotation." The canonical URL must be one of the URLs in the hreflang set, or all hreflang markup is ignored.
+Keep canonical targets and `hreflang` clusters consistent with the chosen content/language strategy. `hreflang` identifies localized alternatives; it does not force Google to index each URL independently. Canonicals are signals to Google's selection process, not an indexing guarantee.
 
-Google also states: "Google prefers URLs that are part of hreflang clusters for canonicalization" -- when signals align, hreflang strengthens canonical selection.
+The preferred canonical must be a URL inside the `hreflang` cluster. Google ignores `hreflang` on a URL that is canonicalized to another one.
 
-- [John Mueller: hreflang canonical](https://johnmu.com/hreflang-canonical/)
-- [SEJ: Hreflang Tags Are Hints](https://www.searchenginejournal.com/google-reminds-that-hreflang-tags-are-hints-not-directives/546428/)
 - [Google: Consolidate Duplicate URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)
 
 ### Near-Duplicate Regional Variants
 
 Mueller (2023 Office Hours): "If the content is completely the same, and we can't tell any difference, then for simplicity and user experience we may just show one version -- even if hreflang is present."
 
-Google's duplicate detection runs BEFORE hreflang evaluation. To keep both versions indexed, you need substantive content differences beyond currency symbols.
+Google may consolidate identical or near-duplicate regional content despite `hreflang`. Use the same-language preferred-canonical strategy above where appropriate; do not promise that either self-canonicals or cosmetic differences will keep every regional URL indexed.
 
 - [International Web Mastery: Same-Language Duplicate Pages](https://internationalwebmastery.com/blog/how-google-handles-canonicalization-of-same-language-duplicate-near-duplicate-pages/)
 - [Google: Managing Multi-Regional Sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites)
@@ -194,7 +192,7 @@ Reddit scaled AI translations to 35+ languages with Google's knowledge. The key
 
 Google: "Localized versions of a page are only considered duplicates if the main content of the page remains untranslated." Pages with only translated boilerplate get clustered as duplicates.
 
-Do NOT use noindex for unwanted locale pages (wastes crawl budget). Do NOT canonical cross-locale (conflicts with hreflang). Best approach: don't create locale pages you can't make genuinely helpful.
+Do NOT use noindex for unwanted locale pages (wastes crawl budget). Do not canonicalize distinct translations to another language merely to hide thin content. Best approach: don't create locale pages you can't make genuinely helpful.
 
 - [Google: Localized Versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
 - [Google: Crawl Budget Management](https://developers.google.com/search/docs/crawling-indexing/large-site-managing-crawl-budget)

package/skills/seo-audit/references/local-seo-pages-and-measurement.md

@@ -0,0 +1,39 @@
+# Location Pages and Measurement
+
+Use this when the request includes local pages, schema, or performance reporting.
+
+## Page Content That Helps a Local Customer
+
+For a real customer-facing location, include accurate location/contact details, hours, services available there, booking/call links, access/parking directions where known, staff or location evidence, and useful nearby/service information. Link it from a location index and relevant service pages.
+
+For service coverage without an office, explain actual availability, constraints, travel or call-out policies, relevant local work examples when available, and a clear enquiry path. Say that it is a service area. Do not show a fake street address or imply a staffed branch.
+
+Example decision: a plumber has one operating base and serves two nearby towns. One honest coverage page may suffice. Separate town pages are justified only by additional useful information or evidence; neither town automatically merits another Business Profile.
+
+Before scaling, confirm a stable data source and meaningful differences across pages. Check the current [doorway-abuse policy](https://developers.google.com/search/docs/essentials/spam-policies#doorway-abuse). Route justified templates to programmatic-seo and hierarchy to site-architecture; consolidate pages when the proposed variants add no value.
+
+## Local Structured Data
+
+Use the most specific accurate LocalBusiness subtype and a stable identifier for each real location. Match the visible page facts; connect the location URL, public phone, hours, and physical coordinates where applicable. Do not mark service cities as invented branches or publish a hidden residential address through JSON-LD.
+
+Important distinction: Schema.org can describe a business without satisfying Google's rich-result requirements. Google's [LocalBusiness documentation](https://developers.google.com/search/docs/appearance/structured-data/local-business) requires an address for that search feature. For a business that cannot publish one, preserve privacy and explain that the rich-result requirement is unmet; do not fabricate an address or promise eligibility from `areaServed` alone.
+
+Self-serving LocalBusiness review markup does not earn review stars merely because the business displays testimonials. Do not import a profile rating into markup as a shortcut to stars.
+
+Use schema for implementation. Validate the rendered page and relevant test tools, then verify deployed markup matches the public content. A stripped text fetch is insufficient proof that JavaScript-injected JSON-LD is absent. Validation does not guarantee display or a local-pack ranking change.
+
+## Measure Customer Outcomes
+
+Keep a baseline by location and period:
+
+| Metric | Evidence | Interpretation limits |
+|---|---|---|
+| Qualified calls/bookings/leads | CRM or owner-confirmed outcomes | Deduplicate; attribution may be incomplete |
+| Profile interactions | Available Business Profile performance export | Interaction is not a completed sale |
+| Organic local queries/pages | Search Console query/page reports | Privacy thresholds and aggregation limit detail |
+| Website actions from profile links | Analytics with consistent campaign tags | Consent, blockers, and tagging can affect counts |
+| Local visibility | Comparable query/location observations | Distance, personalization, and volatility matter |
+
+Use a consistent tagging convention for profile website links while keeping the canonical location URL stable. Test that redirects and booking flows preserve the attribution needed. For call tracking, retain a genuine reachable business contact and verify the platform's current phone rules; do not blindly replace canonical citation numbers.
+
+Review changes against a comparable period, seasonality, opening-hours changes, and service capacity. Record what changed and when. Treat a visibility increase as an observation, not proof of causation or additional revenue. Set follow-up timing with the user rather than promising a universal recovery deadline.

package/skills/seo-audit/references/local-seo-profile-and-citations.md

@@ -0,0 +1,41 @@
+# Profiles and Citations
+
+Use this for profile eligibility, field changes, and name/address/phone cleanup. Verify facts with the owner and the current [business representation guidelines](https://support.google.com/business/answer/3038177).
+
+## Model the Real Business
+
+| Business | Profile approach | Common mistake |
+|---|---|---|
+| Staffed storefront receiving customers | Actual location, public address and customer-facing hours | Keyword-stuffed name or wrong entrance |
+| Service-area business visiting customers | Actual base with address hidden when customers are not served there | Profiles for every city or exposing a home address |
+| Hybrid | Real customer-facing location plus actual coverage | Claiming unstaffed locations |
+| Multiple locations | Verify each location and its staffing/eligibility separately | Assuming a location page or rented mailbox establishes eligibility |
+| Online only | Use organic/AI search strategy appropriate to the business | Creating a fictitious local presence |
+
+Exceptions for practitioners, departments, co-located businesses, and special business types require their specific rules. Do not merge two legitimately distinct entities just because they share an address. An actual relocation needs an update to the existing business identity rather than an unexplained new duplicate.
+
+## Field-Level Review
+
+- **Name:** match real-world branding. Put services and coverage in their proper fields rather than adding search keywords to the name.
+- **Categories:** use the most specific accurate primary category and only justified additional categories. Check the current category options for that market.
+- **Services:** describe services actually offered; distinguish availability, territory, and appointment requirements.
+- **Description:** write factual business/service information. Keep promotions and links out of this field.
+- **Hours and contact:** confirm regular/special hours, correct phone routing, and a location-specific working website/booking link.
+- **Photos:** propose real exterior/entrance, interior, team, or service imagery appropriate to the business. Confirm permission before publishing identifiable customers.
+- **Posts:** use them for relevant current updates, offers, or events where available; do not invent a posting-frequency ranking benefit.
+- **Q&A:** Google [discontinued its Q&A API on November 3, 2025](https://developers.google.com/my-business/content/qanda/change-log). Do not prescribe API seeding or a universal editable Q&A section. Verify current interface availability; answer common customer questions in website content and accurate profile fields when a profile feature is unavailable.
+
+For service areas, confirm actual coverage using [Google's service-area guidance](https://support.google.com/business/answer/9157481). Listing another town does not create a new location or remove searcher distance as a ranking factor.
+
+## Citation Cleanup Table
+
+Use one row per observed listing:
+
+| Location/entity | Listing URL | Observed public facts | Verified source of truth | Correction / duplicate action | Access/status | Verification date |
+|---|---|---|---|---|---|---|
+
+Compare meaning, not merely punctuation: an abbreviation need not be an identity conflict. A wrong phone, old address, mismatched business, or duplicate that diverts customers deserves priority. Preserve location distinctions and legitimate branch phone numbers.
+
+For a home-based service business, use supported hidden-address listings or skip platforms that require publishing private information. Maintain the private operating address separately from public citation data.
+
+Select listings for customer relevance and accurate discovery. Bulk low-quality links, lifetime domain metrics, or a directory count alone do not demonstrate improved local outcomes. DIY corrections are a valid path; paid listing management is optional when its coverage, control, cost, and verification process fit the business.

package/skills/seo-audit/references/local-seo.md

@@ -0,0 +1,86 @@
+# Local SEO
+
+Use this reference when the audit or request is about a local business: Google Business Profile, the map pack, citations, reviews, or location pages.
+
+Help local customers find the right business and turn searches into qualified calls, bookings, and visits. Diagnose the specific location and search context before prescribing changes.
+
+## Start With the Business Model
+
+Read existing product context at `.agents/product-marketing.md` (or `.claude/product-marketing.md`, including older `product-marketing-context.md` setups). Ask only for missing facts relevant to the request:
+
+- Business type: customers visit a storefront, staff travel to customers, both, or online only.
+- Actual operating locations, staffed hours, service coverage, services, and capacity.
+- Website and profile URLs; ownership, verification, duplicates, suspensions, or recent moves.
+- Desired outcome and available evidence: qualified calls, bookings, visits, profile performance, Search Console, and location-level conversion data.
+
+Use the requested scope. A profile description request needs a description, not a compulsory full audit. Without access, provide a provisional plan and identify the evidence needed; never report invented profile findings.
+
+For profile eligibility, address visibility, duplicates, categories, and current feature availability, read [profile-and-citations.md](local-seo-profile-and-citations.md). An online-only business needs a different SEO plan. A service area is not a collection of extra storefronts.
+
+## Diagnose the Local Search Problem
+
+Keep the two surfaces separate:
+
+| Surface | Inspect | Evidence to retain |
+|---|---|---|
+| Maps / local pack | Correct profile, query relevance, searcher distance, reputation | Query, observation date, search location, device/context, profile URL |
+| Organic website results | Indexation, relevant location/service page, content, internal links | Query, page URL, Search Console data where available |
+
+Google describes local ranking through relevance, distance, and prominence. Distance varies with the searcher's location; a larger declared service area does not establish a nearer physical location. Do not promise a top-three placement or a fixed ranking uplift.
+
+Compare like with like: the same queries, locations, observation method, and time window. A single search from the owner's office is not evidence of visibility throughout a city. Separate branded from non-branded demand and label estimates, observed facts, and hypotheses.
+
+Prioritize the constraint supported by evidence:
+
+1. Wrong, ineligible, duplicate, unverified, or suspended profile: resolve the actual issue before adding promotional content.
+2. Customers cannot contact or visit correctly: repair location facts, hours, destination links, and conversion paths.
+3. Relevant demand is not represented: improve accurate categories, service information, and useful location pages.
+4. Weak trust or discovery: address genuine customer feedback, relevant citations, and earned local mentions.
+
+## Improve the Profile and Citation Record
+
+Use [profile-and-citations.md](local-seo-profile-and-citations.md) for the requested profile or listing work. Produce field-level edits grounded in real business facts, with the existing value, proposed value, reason, and missing verification.
+
+Build a canonical location record for the real-world name, public contact details, customer-facing hours, profile ID, and matching location URL. Keep a private operating address separate when customers do not visit it. Never publish a hidden home address merely to satisfy a citation checklist.
+
+Citation cleanup should resolve conflicting identities and customer-facing information. Prioritize relevant maps, local/chamber, and industry listings customers actually use. Correct existing records and merge true duplicates through supported processes before creating more listings. For a software product directory campaign, use directory-submissions; its launch prerequisites and incentive rules are not a local Google review policy.
+
+## Earn and Respond to Reviews
+
+Ask customers with genuine experiences for honest feedback through a neutral request and the correct location's review link. Do not select only happy customers, buy reviews, offer incentives, require particular wording, or promise removal of criticism. Google's rules differ from other review platforms (see the luckiest-referrals skill's review programs reference); read the current [Maps review policy](https://support.google.com/contributionpolicy/answer/7400114?hl=en-GB).
+
+Example request: "Thanks for choosing [business]. If you'd like to share your experience, you can leave a review here: [location review link]. We welcome your honest feedback."
+
+Reply specifically and courteously. For a complaint, acknowledge the concern and offer an appropriate private contact path without exposing customer, medical, financial, or job details. Report a policy violation through the platform's process; an unfavorable genuine opinion is not automatically removable.
+
+Track recurring feedback and service improvements alongside review volume and recency. A rating target must not become a staff quota for soliciting specified review content.
+
+## Build Useful Location and Service Pages
+
+Read [location-pages-and-measurement.md](local-seo-pages-and-measurement.md) when building pages, preparing local schema, or measuring results.
+
+Give each real location a useful destination. A service-area page describes verified service coverage; it must not imply an office that does not exist. Publish a city page only when it adds meaningful local information, evidence, or customer utility. Swapping city names in duplicated text does not create that value.
+
+Route implementation details to the relevant existing skill:
+
+- **The rest of this skill (seo-audit):** crawling, indexing, redirects, speed, and technical diagnosis.
+- **site-architecture:** location hierarchy, navigation, and internal links.
+- **programmatic-seo:** scaling a justified page pattern backed by real data.
+- **schema:** markup implementation after choosing accurate, public business facts.
+- **ai-seo:** visibility in AI answers when that is part of the request.
+
+## Return a Decision and an Actionable Artifact
+
+For an audit or plan, return:
+
+1. Business model and the specific location/search surface assessed.
+2. Findings with source, date, customer impact, confidence, and missing evidence.
+3. Prioritized changes with a responsible owner and a way to verify completion.
+4. The requested artifact: field edits, citation cleanup table, review drafts, location-page outline, or measurement plan.
+5. Follow-up measures tied to qualified customer actions rather than rankings alone.
+
+For narrow requests, deliver the artifact directly and state only the relevant assumptions. Drafting a plan does not itself authorize profile changes, messages to customers, or directory submissions; follow the user's existing authorization for execution.
+
+## Sources
+
+Check current platform rules when a recommendation depends on them. The references link directly to the relevant Google documentation, including retired Q&A functionality and the distinction between Schema.org validity and Google rich-result eligibility.

package/skills/seo-audit/references/rankings-push.md

@@ -0,0 +1,62 @@
+# Rankings Push
+
+Audits find what's broken. This reference covers the next step: moving pages that already rank onto page one, and shipping new pages so they start strong. Both are cheaper than winning a query from nothing, because Google has already decided the site is relevant.
+
+## Find the candidates
+
+From Search Console, pull query + page pairs for the trailing 28 days (compare with the previous period to filter out spikes):
+
+| Bucket | Filter | Fix type |
+|--------|--------|----------|
+| **Striking distance** | Average position 8–20, impressions above a floor that fits the site (often 100+/month) | Content and links |
+| **Weak click-through** | Position 1–5, CTR well below other pages at similar positions | Title and meta description |
+| **Near the top** | Position 4–7 on a revenue query | Content, links, and featured-snippet format |
+
+Prioritize by business value: a position-11 query that drives demos beats a position-9 glossary term with three times the impressions.
+
+Before touching a page, check for **cannibalization**: if two of your pages rank for the same query, positions often bounce between them and neither climbs. Pick one owner, merge the useful parts of the other into it, and redirect.
+
+## Diagnose against the top three
+
+Open the three results above you and write down, for each one, the concrete reason it wins. Usually one of these:
+
+- **Intent match.** They answer the question the searcher is asking; your page answers a neighboring one. A pricing query answered with a features page loses.
+- **A missing section.** They cover a sub-question you skip. The People Also Ask box and the subheadings across the top results show what searchers expect.
+- **Freshness.** Their facts, screenshots, or year are current and yours aren't.
+- **Format.** They have the table, steps, or tool the query calls for.
+- **Links.** They're linked from more, and stronger, pages, inside their site and out.
+
+If you can't name a reason, don't guess with a rewrite. The gap is more likely authority than on-page, and the fix is links (the `backlink-prospecting` loop in `marketing-loops`) rather than content.
+
+## Make the smallest change that closes the gap
+
+- **Answer the query in the first two sentences**, then expand. This is also the passage AI Overviews and assistants tend to quote.
+- **Add the missing section**, not a rewrite of the whole page. Pages that already rank have signals worth keeping.
+- **Put the query in the title and H1** if it reads naturally. If the title is already aligned, leave it.
+- **Add internal links to the page** from your strongest related pages, with anchor text that describes the target. This is often the biggest single lever and the most neglected.
+- **Refresh what's stale**: facts, screenshots, the year, broken links.
+- **For weak click-through only**, change the title and meta description and nothing else, so the result is attributable. Patterns in [title-tags.md](title-tags.md).
+
+Record the starting position, impressions, and CTR, then wait 3–4 weeks before judging or changing the page again. Rankings take time to settle after an edit, and stacked changes make it impossible to know what worked.
+
+If two rounds move nothing, stop editing. The page is probably limited by intent mismatch (Google wants a different kind of page) or authority, and more on-page work won't fix either.
+
+## Shipping a new page
+
+A new page should launch with everything it needs to be found, so it doesn't spend months as an orphan:
+
+- [ ] Internal links from at least three relevant existing pages, with descriptive anchors
+- [ ] Unique title and meta description matching the target query
+- [ ] One H1, aligned with the title
+- [ ] Self-referencing canonical
+- [ ] Added to the XML sitemap
+- [ ] Structured data where the page type supports it (see `luckiest-schema`)
+- [ ] Main content present in the server-rendered HTML, not only after JavaScript runs
+- [ ] Indexable: no stray `noindex`, not blocked in robots.txt
+- [ ] Linked to the right conversion path (see `cro`)
+
+After it ships, request indexing once in Search Console. Requesting again doesn't speed anything up. If the page isn't indexed after a few weeks, check the causes in the Indexation section of the audit instead of resubmitting.
+
+## Run it on a schedule
+
+Run this weekly with state, cooldowns, and a stop rule, so the same page is not pushed again before its last change has had time to show.