@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/marketing-ops/references/acquire/seo-audit.md

@@ -0,0 +1,546 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20
+stage: acquire
+upstream_path: skills/seo-audit/SKILL.md
+---
+
+> **Adjacency:** This skill is part of the [`marketing-ops`](../../SKILL.md) umbrella, organized by funnel stage (acquire). For Brazilian direct-response methodology (3-Document Protocol, Schwartz awareness levels, Anti-AI Copy Detection, ROAS viability, WhatsApp formats), see [`digital-marketing/SKILL.md`](../../../digital-marketing/SKILL.md). For page-level SaaS copy, see [`general/copywriting/SKILL.md`](../../../../general/copywriting/SKILL.md). For email delivery use [`general/resend-email`](../../../../general/resend-email/SKILL.md), for visuals [`general/image-gen`](../../../../general/image-gen/SKILL.md), for decks [`general/blkskrn`](../../../../general/blkskrn/SKILL.md).
+
+---
+
+# SEO Audit
+
+You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.
+
+## Initial Assessment
+
+**Check for product marketing context first:**
+If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Before auditing, understand:
+
+1. **Site Context**
+   - What type of site? (SaaS, e-commerce, blog, etc.)
+   - What's the primary business goal for SEO?
+   - What keywords/topics are priorities?
+
+2. **Current State**
+   - Any known issues or concerns?
+   - Current organic traffic level?
+   - Recent changes or migrations?
+
+3. **Scope**
+   - Full site audit or specific pages?
+   - Technical + on-page, or one focus area?
+   - Access to Search Console / analytics?
+
+---
+
+## Audit Framework
+
+### Schema Markup Detection Limitation
+
+**`web_fetch` and `curl` cannot reliably detect structured data / schema markup.**
+
+Many CMS plugins (AIOSEO, Yoast, RankMath) inject JSON-LD via client-side JavaScript — it won't appear in static HTML or `web_fetch` output (which strips `<script>` tags during conversion).
+
+**To accurately check for schema markup, use one of these methods:**
+
+1. **Browser tool** — render the page and run: `document.querySelectorAll('script[type="application/ld+json"]')`
+2. **Google Rich Results Test** — https://search.google.com/test/rich-results
+3. **Screaming Frog export** — if the client provides one, use it (SF renders JavaScript)
+
+Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false audit findings — these tools can't see JS-injected schema.
+
+### Priority Order
+
+1. **Crawlability & Indexation** (can Google find and index it?)
+2. **Technical Foundations** (is the site fast and functional?)
+3. **On-Page Optimization** (is content optimized?)
+4. **Content Quality** (does it deserve to rank?)
+5. **Authority & Links** (does it have credibility?)
+
+---
+
+## Technical SEO Audit
+
+### Crawlability
+
+**Robots.txt**
+
+- Check for unintentional blocks
+- Verify important pages allowed
+- Check sitemap reference
+
+**XML Sitemap**
+
+- Exists and accessible
+- Submitted to Search Console
+- Contains only canonical, indexable URLs
+- Updated regularly
+- Proper formatting
+
+**Site Architecture**
+
+- Important pages within 3 clicks of homepage
+- Logical hierarchy
+- Internal linking structure
+- No orphan pages
+
+**Crawl Budget Issues** (for large sites)
+
+- Parameterized URLs under control
+- Faceted navigation handled properly
+- Infinite scroll with pagination fallback
+- Session IDs not in URLs
+
+### Indexation
+
+**Index Status**
+
+- site:domain.com check
+- Search Console coverage report
+- Compare indexed vs. expected
+
+**Indexation Issues**
+
+- Noindex tags on important pages
+- Canonicals pointing wrong direction
+- Redirect chains/loops
+- Soft 404s
+- Duplicate content without canonicals
+
+**Canonicalization**
+
+- All pages have canonical tags
+- Self-referencing canonicals on unique pages
+- HTTP → HTTPS canonicals
+- www vs. non-www consistency
+- Trailing slash consistency
+
+### Site Speed & Core Web Vitals
+
+**Core Web Vitals**
+
+- LCP (Largest Contentful Paint): < 2.5s
+- INP (Interaction to Next Paint): < 200ms
+- CLS (Cumulative Layout Shift): < 0.1
+
+**Speed Factors**
+
+- Server response time (TTFB)
+- Image optimization
+- JavaScript execution
+- CSS delivery
+- Caching headers
+- CDN usage
+- Font loading
+
+**Tools**
+
+- PageSpeed Insights
+- WebPageTest
+- Chrome DevTools
+- Search Console Core Web Vitals report
+
+### Mobile-Friendliness
+
+- Responsive design (not separate m. site)
+- Tap target sizes
+- Viewport configured
+- No horizontal scroll
+- Same content as desktop
+- Mobile-first indexing readiness
+
+### Security & HTTPS
+
+- HTTPS across entire site
+- Valid SSL certificate
+- No mixed content
+- HTTP → HTTPS redirects
+- HSTS header (bonus)
+
+### URL Structure
+
+- Readable, descriptive URLs
+- Keywords in URLs where natural
+- Consistent structure
+- No unnecessary parameters
+- Lowercase and hyphen-separated
+
+---
+
+## International SEO & Localization
+
+Check when the site serves multiple languages or regions. Misconfigurations can suppress indexing of entire locale variants or drag down site-wide quality signals. See [International SEO reference](references/international-seo.md) for evidence and source URLs.
+
+### Hreflang
+
+Three equivalent placement methods: HTML `<link>` in `<head>`, HTTP `Link` headers, XML sitemap `<xhtml:link>`. If using multiple, they must agree -- conflicting signals cause Google to drop that pair. For 10+ locales, prefer sitemap-based (no page weight, no per-request cost).
+
+**Check for:**
+
+- Self-referencing entry on every page (page must include itself in the hreflang set)
+- Reciprocal links (if A points to B, B must point back to A -- or both are ignored)
+- Valid codes: ISO 639-1 language + optional ISO 3166-1 Alpha 2 region (e.g., `en`, `en-GB` -- never `en-UK`)
+- `x-default` present, pointing to fallback page (language selector or default locale)
+- All target URLs return 200, are indexable, and match their canonical URL
+- No duplicate language-region codes pointing to different URLs
+
+**Common errors:** Missing self-referencing entry (all hreflang ignored). No return tag / one-directional (pair dropped). Invalid codes like `en-UK` (use `en-GB`). Hreflang target is non-canonical, 404, or blocked (cluster discarded). HTML and sitemap annotations disagree (conflicting pair dropped).
+
+**At scale:** `<xhtml:link>` children don't count toward 50K URL sitemap limit, but the 50MB file size limit becomes the bottleneck (plan 2K-5K URLs per file with full hreflang). Focus hreflang on pages receiving wrong-language traffic -- not required on every page. For Bing: supplement with `<html lang>` and `<meta http-equiv="content-language">` (Bing treats hreflang as a weak signal).
+
+### Canonicalization for Multilingual Sites
+
+- Each locale page must self-canonical (e.g., `/ar/page` canonicals to `/ar/page`)
+- Never cross-locale canonical (French to English) -- suppresses the non-canonical locale entirely
+- Canonical URL must appear in the hreflang set -- if not, all hreflang is ignored
+- Canonical overrides hreflang when they conflict
+- Protocol/domain must be consistent across canonical, hreflang, and sitemap (`https` + same domain variant)
+- Paginated locale pages: self-referencing canonical per page (never canonical page 2+ to page 1)
+
+**Common mistakes:** all locales canonical to English (kills indexing), canonical URL not in hreflang set (silently ignored), protocol mismatch between canonical and hreflang, CMS setting deep page canonical to homepage.
+
+### International Sitemaps
+
+**Check for:**
+
+- `xmlns:xhtml` namespace on `<urlset>`, each `<url>` includes `<xhtml:link>` for all locales including itself
+- `x-default` alternate included; all URLs absolute (full protocol + domain)
+- Sitemap index in Search Console and robots.txt; split by content type, not by locale
+
+**Next.js caveat:** `alternates.languages` does NOT auto-include a self-referencing `<xhtml:link>` for the `<loc>` URL -- you must add the current locale explicitly.
+
+### Locale URL Structure
+
+**Recommended:** Subdirectories (`/en/`, `/ar/`). **Acceptable:** Subdomains or ccTLDs. **Not recommended:** URL parameters (`?lang=en`).
+
+**Check for:**
+
+- Consistent locale prefix strategy; all locales prefixed (hiding locale from URLs prevents Google from distinguishing versions)
+- Root URL handled as `x-default` with redirect, or serves default locale content
+- No IP/Accept-Language content negotiation (Googlebot: US IPs, no Accept-Language header)
+- Trailing slash + case consistency across locale paths, canonicals, hreflang, and sitemaps
+- 301 redirects from non-canonical format to canonical
+
+**Note:** Google's International Targeting report in Search Console is deprecated. Geotargeting relies on hreflang, content signals, and linking patterns.
+
+### Content Quality Across Locales
+
+**Translation quality:**
+
+- AI-translated content is not inherently spam (Google's 2025 stance), but scaled low-value translations can trigger scaled content abuse policy
+- Google uses visible content to determine language -- translate ALL page content (title, description, headings, body), not just boilerplate
+- Translating only template/nav while main content stays in original language creates duplicates
+
+**Thin locale pages:**
+
+- Helpful content system is site-wide -- many thin locale pages can suppress rankings for strong pages too
+- Don't noindex thin locales (wastes crawl budget) or cross-locale canonical (conflicts with hreflang)
+- Best approach: don't create locale pages you cannot make genuinely helpful
+
+**Check for:**
+
+- All locale pages have fully translated main content (not just UI chrome)
+- No near-identical content across locales ("Duplicate, Google chose different canonical" in GSC)
+- Hreflang only for locales with genuine content and search demand
+- Localized signals: currency, phone format, addresses where applicable
+- Broken hreflang links (404s, redirects) waste crawl budget AND invalidate hreflang clusters
+
+---
+
+## On-Page SEO Audit
+
+### 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)
+
+**Common issues:**
+
+- Duplicate titles
+- Too long (truncated)
+- Too short (wasted opportunity)
+- Keyword stuffing
+- Missing entirely
+
+### Meta Descriptions
+
+**Check for:**
+
+- Unique descriptions per page
+- 150-160 characters
+- Includes primary keyword
+- Clear value proposition
+- Call to action
+
+**Common issues:**
+
+- Duplicate descriptions
+- Auto-generated garbage
+- Too long/short
+- No compelling reason to click
+
+### Heading Structure
+
+**Check for:**
+
+- One H1 per page
+- H1 contains primary keyword
+- Logical hierarchy (H1 → H2 → H3)
+- Headings describe content
+- Not just for styling
+
+**Common issues:**
+
+- Multiple H1s
+- Skip levels (H1 → H3)
+- Headings used for styling only
+- No H1 on page
+
+### Content Optimization
+
+**Primary Page Content**
+
+- Keyword in first 100 words
+- Related keywords naturally used
+- Sufficient depth/length for topic
+- Answers search intent
+- Better than competitors
+
+**Thin Content Issues**
+
+- Pages with little unique content
+- Tag/category pages with no value
+- Doorway pages
+- Duplicate or near-duplicate content
+
+### Image Optimization
+
+**Check for:**
+
+- Descriptive file names
+- Alt text on all images
+- Alt text describes image
+- Compressed file sizes
+- Modern formats (WebP)
+- Lazy loading implemented
+- Responsive images
+
+### Internal Linking
+
+**Check for:**
+
+- Important pages well-linked
+- Descriptive anchor text
+- Logical link relationships
+- No broken internal links
+- Reasonable link count per page
+
+**Common issues:**
+
+- Orphan pages (no internal links)
+- Over-optimized anchor text
+- Important pages buried
+- Excessive footer/sidebar links
+
+### Keyword Targeting
+
+**Per Page**
+
+- Clear primary keyword target
+- Title, H1, URL aligned
+- Content satisfies search intent
+- Not competing with other pages (cannibalization)
+
+**Site-Wide**
+
+- Keyword mapping document
+- No major gaps in coverage
+- No keyword cannibalization
+- Logical topical clusters
+
+---
+
+## Content Quality Assessment
+
+### E-E-A-T Signals
+
+**Experience**
+
+- First-hand experience demonstrated
+- Original insights/data
+- Real examples and case studies
+
+**Expertise**
+
+- Author credentials visible
+- Accurate, detailed information
+- Properly sourced claims
+
+**Authoritativeness**
+
+- Recognized in the space
+- Cited by others
+- Industry credentials
+
+**Trustworthiness**
+
+- Accurate information
+- Transparent about business
+- Contact information available
+- Privacy policy, terms
+- Secure site (HTTPS)
+
+### Content Depth
+
+- Comprehensive coverage of topic
+- Answers follow-up questions
+- Better than top-ranking competitors
+- Updated and current
+
+### User Engagement Signals
+
+- Time on page
+- Bounce rate in context
+- Pages per session
+- Return visits
+
+---
+
+## Common Issues by Site Type
+
+### SaaS/Product Sites
+
+- Product pages lack content depth
+- Blog not integrated with product pages
+- Missing comparison/alternative pages
+- Feature pages thin on content
+- No glossary/educational content
+
+### E-commerce
+
+- Thin category pages
+- Duplicate product descriptions
+- Missing product schema
+- Faceted navigation creating duplicates
+- Out-of-stock pages mishandled
+
+### Content/Blog Sites
+
+- Outdated content not refreshed
+- Keyword cannibalization
+- No topical clustering
+- Poor internal linking
+- Missing author pages
+
+### Multilingual / Multi-Regional Sites
+
+- Hreflang errors (missing return tags, invalid codes, no self-reference)
+- Canonical conflicting with hreflang (cross-locale canonical suppresses indexing)
+- Thin locale pages dragging down site-wide quality signal
+- Only boilerplate translated, main content identical across locales
+- No x-default fallback declared
+- Sitemap missing hreflang alternates or missing reciprocal entries
+- IP-based redirects hiding content from Googlebot
+- Framework locale mode hiding locale from URLs
+
+### Local Business
+
+- Inconsistent NAP
+- Missing local schema
+- No Google Business Profile optimization
+- Missing location pages
+- No local content
+
+---
+
+## Output Format
+
+### Audit Report Structure
+
+**Executive Summary**
+
+- Overall health assessment
+- Top 3-5 priority issues
+- Quick wins identified
+
+**Technical SEO Findings**
+For each issue:
+
+- **Issue**: What's wrong
+- **Impact**: SEO impact (High/Medium/Low)
+- **Evidence**: How you found it
+- **Fix**: Specific recommendation
+- **Priority**: 1-5 or High/Medium/Low
+
+**On-Page SEO Findings**
+Same format as above
+
+**Content Findings**
+Same format as above
+
+**Prioritized Action Plan**
+
+1. Critical fixes (blocking indexation/ranking)
+2. High-impact improvements
+3. Quick wins (easy, immediate benefit)
+4. Long-term recommendations
+
+---
+
+## References
+
+- [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid (em dashes, overused phrases, filler words)
+- [International SEO](references/international-seo.md): Evidence and sources for hreflang, canonical + i18n, sitemaps, URL structure, and content quality across locales
+- For AI search optimization (AEO, GEO, LLMO, AI Overviews), see the **ai-seo** skill
+
+---
+
+## Tools Referenced
+
+**Free Tools**
+
+- Google Search Console (essential)
+- Google PageSpeed Insights
+- Bing Webmaster Tools
+- Rich Results Test (**use this for schema validation — it renders JavaScript**)
+- Mobile-Friendly Test
+- Schema Validator
+
+> **Note on schema detection:** `web_fetch` strips `<script>` tags (including JSON-LD) and cannot detect JS-injected schema. Use the browser tool, Rich Results Test, or Screaming Frog instead — they render JavaScript and capture dynamically-injected markup. See the Schema Markup Detection Limitation section above.
+
+**Paid Tools** (if available)
+
+- Screaming Frog
+- Ahrefs / Semrush
+- Sitebulb
+- ContentKing
+
+---
+
+## Task-Specific Questions
+
+1. What pages/keywords matter most?
+2. Do you have Search Console access?
+3. Any recent changes or migrations?
+4. Who are your top organic competitors?
+5. What's your current organic traffic baseline?
+
+---
+
+## Related Skills
+
+- **ai-seo**: For optimizing content for AI search engines (AEO, GEO, LLMO)
+- **programmatic-seo**: For building SEO pages at scale
+- **site-architecture**: For page hierarchy, navigation design, and URL structure
+- **schema**: For implementing structured data
+- **cro**: For optimizing pages for conversion (not just ranking)
+- **analytics**: For measuring SEO performance

package/.merlin-core/skills/domain/marketing-ops/references/acquire/site-architecture/references/mermaid-templates.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: site-architecture
+upstream_path: skills/site-architecture/references/mermaid-templates.md
+---
+
+# mermaid-templates — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/site-architecture/references/mermaid-templates.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/site-architecture/references/mermaid-templates.md
+
+**Parent skill:** [`../site-architecture.md`](../site-architecture.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/site-architecture/references/mermaid-templates.md`, then prepend the standard Adjacency header.

package/.merlin-core/skills/domain/marketing-ops/references/acquire/site-architecture/references/navigation-patterns.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: site-architecture
+upstream_path: skills/site-architecture/references/navigation-patterns.md
+---
+
+# navigation-patterns — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/site-architecture/references/navigation-patterns.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/site-architecture/references/navigation-patterns.md
+
+**Parent skill:** [`../site-architecture.md`](../site-architecture.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/site-architecture/references/navigation-patterns.md`, then prepend the standard Adjacency header.

package/.merlin-core/skills/domain/marketing-ops/references/acquire/site-architecture/references/site-type-templates.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: site-architecture
+upstream_path: skills/site-architecture/references/site-type-templates.md
+---
+
+# site-type-templates — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/site-architecture/references/site-type-templates.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/site-architecture/references/site-type-templates.md
+
+**Parent skill:** [`../site-architecture.md`](../site-architecture.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/site-architecture/references/site-type-templates.md`, then prepend the standard Adjacency header.