optbrew 0.0.0-stage → 0.1.1

package/skills/optbrew/modules/seranking-seo/skills/seo-schema/GUIDE.md

@@ -0,0 +1,135 @@
+> Example output: examples/seo-schema-budgetbytes-slow-cooker-chicken-noodle-soup-20260514/SCHEMA.md (upstream-only reference; route through optbrew)
+
+# Schema Markup
+
+Detect, validate, and generate Schema.org JSON-LD for a page. Output is paste-ready `<script>` blocks the user can drop into their CMS or page template, plus a validation report on what's currently present and what's broken.
+
+## Prerequisites
+
+- **Required for detect/validate paths:** `mcp__firecrawl-mcp__firecrawl_scrape` (raw HTML access). WebFetch returns markdown only — every `<script type="application/ld+json">` block is stripped before the skill ever sees it. Without Firecrawl, the skill can still generate new schema from intent detection (steps 4–6) but cannot detect or validate what's already on the page (steps 2–3, 7).
+- Optional: SE Ranking MCP server (used in step 7 for benchmarking competitor schema).
+- User provides: a target URL. Optionally a hint about page intent ("this is a product page", "this is a how-to") if the URL pattern doesn't make it obvious.
+
+## Process
+
+1. **Fetch HTML** `mcp__firecrawl-mcp__firecrawl_scrape` (preferred) or degrade
+   - **Cost note.** Firecrawl: 1 credit for the target URL, +10 credits if step 7 (competitor benchmark) runs (1 per top-10 SERP result). User may pass `--no-firecrawl` to force the degraded path (generate-only mode) for credit conservation.
+   - **If Firecrawl available:** scrape the target URL. For SPAs, pass `waitFor: 2000` (or a CSS selector for the main content) so the JS-rendered DOM is captured. Use the response's `html` for JSON-LD parsing in step 2 and `metadata` for canonical/robots cross-reference.
+   - **If Firecrawl unavailable:** skip steps 2, 3, and 7 entirely (they all need raw HTML). Steps 4–6 still run — the skill becomes "generate-only", producing recommended JSON-LD blocks from intent detection without comparing to what's on the page. Surface clearly in `SCHEMA.md`: `Existing-schema detection: skipped — Firecrawl required (WebFetch returns markdown only). Install via optbrew capability setup (see top-level routing).`
+   - Even with Firecrawl: if JSON-LD blocks appear only after JS render, flag in the output: "JS-rendered schema may not be detected by all crawlers — server-side render JSON-LD where possible."
+
+2. **Detect existing schema** (requires Firecrawl HTML from step 1)
+   - From the returned `html`: extract every `<script type="application/ld+json">` block.
+   - Parse each as JSON. Report syntax errors.
+   - List each detected `@type`.
+   - Also detect Microdata (`itemscope`/`itemprop`) and RDFa (`typeof`/`property`) — flag as legacy and recommend migration to JSON-LD (Google's stated preference).
+   - **If step 1 degraded:** skip this step. Record `Existing-schema detection skipped` in `01-detected.md`.
+
+3. **Validate against Google's spec**
+   - Load `references/google-rich-results.md`.
+   - For each detected `@type`, check required and recommended properties.
+   - Surface common errors: missing `@context`, dates not in ISO 8601, prices as numbers instead of strings, `availability` as plain text instead of schema.org URL, telephone not in international format.
+
+4. **Detect page intent**
+   - From URL pattern (`/blog/`, `/products/`, `/contact/`, `/how-to/`, `/faq/`).
+   - From `<title>` and `<h1>` tone.
+   - From content signals (numbered list of steps → HowTo; visible Q&A blocks → FAQPage; price + buy button → Product; address + hours → LocalBusiness).
+   - If multiple intents detected, generate schema for each.
+
+5. **Generate missing JSON-LD**
+   - For each detected intent without matching valid schema, load the relevant template from `templates/`:
+     - `article.json` — for editorial/blog content
+     - `product.json` — for product/SKU pages
+     - `local-business.json` — for brick-and-mortar landing pages
+     - `faq-page.json` — for explicit Q&A blocks (gov/health allowlist only — see references/google-rich-results.md)
+     - `breadcrumb-list.json` — for any page with breadcrumb navigation
+   - Fill template fields from the live HTML (title → headline, h2s → mainEntity questions, etc.).
+   - Mark any field that couldn't be auto-filled as `{REPLACE: ...}` so the user knows to complete it.
+   - **Don't generate `HowTo`** — Google retired HowTo rich results in September 2023 (mobile + desktop). The schema can still ship for semantic clarity, but expect zero rich-result uplift; flag this in the recommendation rationale rather than treating HowTo as a live option.
+
+6. **Validate generated JSON-LD**
+   - Re-run the same validation rubric from step 3 on the generated blocks.
+   - Surface any required fields still marked `{REPLACE: ...}`.
+
+7. **Optional: benchmark against top SERP results** `DATA_getSerpResults` + `mcp__firecrawl-mcp__firecrawl_scrape`
+   - Identify the page's primary keyword (from `<title>` or user input).
+   - Pull top 10 organic results.
+   - **If Firecrawl available:** scrape each of the top 10 (10 Firecrawl credits). For each, parse JSON-LD blocks from the returned `html` and list detected `@type`s. This produces real schema data, not inferences from markdown.
+   - **If Firecrawl unavailable:** skip the benchmark — WebFetch's markdown strips all schema blocks, so any "detection" from it would be guesswork. Write `Competitor benchmark skipped — Firecrawl required to read JSON-LD from competitor pages.` into `04-competitor-benchmark.md`.
+   - Surface "schema types used by 6+ of the top 10 that this page is missing." High-signal addition list. (Only emitted when benchmark ran.)
+
+8. **Synthesise** `SCHEMA.md`
+   - Validation report (existing schema, pass/fail per block).
+   - Recommended additions (with rationale linking back to step 4 detection or step 7 benchmark).
+   - Generated `<script>` blocks ready to paste.
+
+## Output format
+
+Create a folder `seo-schema-{target-slug}-{YYYYMMDD}/` with:
+
+```
+seo-schema-{target-slug}-{YYYYMMDD}/
+├── 01-detected.md           (existing schema, validation results)
+├── 02-recommended.md        (which types this page should add and why)
+├── 03-generated/
+│   ├── article.jsonld
+│   ├── faq-page.jsonld
+│   └── ... (per generated type)
+├── 04-competitor-benchmark.md  (only if step 7 ran)
+└── SCHEMA.md                (deliverable: paste-ready blocks + install instructions)
+```
+
+`SCHEMA.md` follows this shape:
+
+```markdown
+# Schema Markup: {URL}
+
+> Snapshot dated {YYYY-MM-DD}.
+
+## Currently present
+- `Article` — valid ✓
+- `BreadcrumbList` — invalid ✗ (missing `position` on item 2)
+- ...
+
+## Recommended additions
+- `FAQPage` — page has 6 visible Q&A blocks but no FAQ schema. Adding this is eligible for FAQ rich results (subject to Google's 2024+ tightening — see references/google-rich-results.md).
+- `HowTo` — ...
+
+## Paste these into the `<head>` of the page
+
+### FAQPage
+\`\`\`html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [...]
+}
+</script>
+\`\`\`
+
+### ... (per generated block)
+
+## Validation pass
+- All generated blocks parse cleanly ✓
+- All required fields filled ({n} {REPLACE: ...} placeholders remain — see below)
+- {REPLACE: ...} placeholders to fill manually:
+  - article.jsonld → `image` (need a hero image URL ≥ 1200×800)
+  - ...
+
+## Install
+1. Copy each `<script>` block above.
+2. Paste into the `<head>` of the relevant page (or the global `<head>` template, gated by page type).
+3. Test with [Google's Rich Results Test](https://search.google.com/test/rich-results).
+4. Submit the URL to GSC for re-indexing if changes are critical.
+```
+
+## Tips
+
+- JSON-LD goes in `<head>` or top of `<body>`. Don't bury it.
+- Test every generated block in [Google's Rich Results Test](https://search.google.com/test/rich-results) before shipping. The validation in step 3/6 follows the published spec but Google's actual test is authoritative.
+- `references/google-rich-results.md` is dated. If it's >6 months old when you run this skill, flag staleness in the output and recommend the user verify against current docs.
+- **Don't mark up content that isn't visibly on the page.** Google penalises hidden-content schema. If a page doesn't actually have FAQs visible, don't generate FAQPage schema.
+- For Article schema, `image` is required. If the page has no obvious hero image, leave the `{REPLACE: hero image URL}` placeholder rather than guessing.
+- The skill is read-mostly on the SE Ranking side: zero SE Ranking credits unless step 7 (competitor benchmark) is requested — that adds ~5–10 SE Ranking credits for `DATA_getSerpResults`. Firecrawl costs are separate: 1 credit for the target URL, +10 credits when step 7 runs.
+- **Verify after deploy:** once the generated schema is pasted into your CMS and re-deployed, re-run this skill on the same URL — the new run's "Currently present" section reflects the live state and confirms the schema actually rendered (vs sitting in the CMS but not yet pushed). Ad-hoc alternative: invoke `seo-firecrawl` on the URL and grep `META.md` for the expected `@type`s.

package/skills/optbrew/modules/seranking-seo/skills/seo-schema/references/google-rich-results.md

@@ -0,0 +1,89 @@
+# Google Rich Results — supported types and requirements
+
+> **Last reviewed: 2026-04-27.** Google updates supported types and requirements regularly. This file is a guide, not authoritative. Verify in [Google's Rich Results Test](https://search.google.com/test/rich-results) and the [Search Gallery](https://developers.google.com/search/docs/appearance/structured-data/search-gallery).
+
+## Type lifecycle (as of April 2026)
+
+Use this table to decide whether a type is worth generating *for rich results*. Schema can still ship for semantic clarity even when the rich-result hook is dead — but the user should know up front.
+
+| Type | Status | Effective date | What it means today |
+|---|---|---|---|
+| `Article` / `NewsArticle` / `BlogPosting` | **Active** | — | Eligible for top-stories, AI-overview citation hints, host carousels. Stable since 2018. |
+| `Product` (with `Offer`) | **Active** | — | Price/availability/rating pills in SERP. Stable. |
+| `LocalBusiness` (+ subtypes) | **Active** | — | Knowledge-panel feed, local pack enrichment. Stable. |
+| `BreadcrumbList` | **Active** | — | Breadcrumb trail in SERP snippet. High-signal, cheap to ship. |
+| `VideoObject` | **Active** | — | Video result + key-moments. |
+| `Recipe` | **Active** | — | Recipe carousel + ingredients in SERP. Cooking-only since the HowTo deprecation. |
+| `Event` | **Active** | — | Event listing pill + Google Events. |
+| `JobPosting` | **Active** | — | Google for Jobs listing. |
+| `Course` / `CourseInfo` | **Active** | — | Course listing pill. |
+| `Movie` | **Active** | — | Movie carousel. |
+| `Organization` | **Active** | — | Knowledge-panel logo + sameAs. |
+| `WebSite` (with `SiteNavigationElement`) | **Active** | — | Sitelinks + sitelinks search box. |
+| `FAQPage` | **Restricted** | 2023-08 | Rich results limited to "well-known authoritative government and health" sites. For everyone else, ship only if the page is unambiguously a dedicated FAQ — expect zero SERP uplift. |
+| `Q&APage` | **Restricted** | 2023-08 | Same restriction as `FAQPage`. Limited to forum/community use cases. |
+| `HowTo` | **Deprecated** | 2023-09 | Rich results removed from desktop and mobile (full retirement Sep 2023). Schema no longer drives any SERP feature for non-cooking content. **Do not generate** — use plain prose + step images. |
+| `Sitelinks Search Box` | **Deprecated** | 2024-11 | Google stopped using `potentialAction.SearchAction` to render the search box. Markup is harmless but inert. |
+
+> ⚠ **Status-check rule:** if this file is more than 6 months old at run-time, flag staleness and verify against [Google's Search Gallery](https://developers.google.com/search/docs/appearance/structured-data/search-gallery) before recommending. Status changes here ship without warning from Google.
+
+## Supported types (April 2026 — bundled templates)
+
+| Schema.org type | When to use | Template |
+|---|---|---|
+| `Article` / `NewsArticle` / `BlogPosting` | Editorial content with an author | `templates/article.json` |
+| `Product` (with `Offer`) | E-commerce product page | `templates/product.json` |
+| `LocalBusiness` (and subtypes like `Restaurant`, `Dentist`) | Brick-and-mortar landing page | `templates/local-business.json` |
+| `FAQPage` | Page with explicit Q&A blocks (gov/health only — see Restricted in lifecycle table) | `templates/faq-page.json` |
+| `BreadcrumbList` | Most pages with breadcrumb navigation | `templates/breadcrumb-list.json` |
+| `VideoObject` | Pages embedding video content | (template not bundled — see Google docs) |
+| `Recipe` | Cooking recipes | (template not bundled) |
+| `Event` | Time-bound events | (template not bundled) |
+
+## Required vs recommended (highlights)
+
+### Article / NewsArticle / BlogPosting
+- **Required:** `headline`, `image`, `datePublished`
+- **Recommended:** `author` (with `@type: Person` and `url`), `dateModified`, `publisher` (with logo `ImageObject`), `mainEntityOfPage`
+- **Common errors:** `headline` over 110 chars; missing `image` or image too small (min 1200×800 for max coverage); `author` as plain string instead of `@type: Person`.
+
+### Product
+- **Required:** `name`, `image`, `offers` (with `price`, `priceCurrency`, `availability`)
+- **Recommended:** `aggregateRating`, `review`, `sku`, `brand`, `gtin`/`mpn`
+- **Common errors:** `price` as a number instead of string; `availability` as plain text instead of schema.org URL (`https://schema.org/InStock`).
+
+### LocalBusiness
+- **Required:** `name`, `address` (full `PostalAddress`), `telephone` OR `url`
+- **Recommended:** `geo`, `openingHoursSpecification`, `priceRange`, `image`, `aggregateRating`
+- **Common errors:** `telephone` not in international format (must include country code, no spaces in JSON-LD); `address` as plain string instead of `@type: PostalAddress`.
+
+### FAQPage
+- **Required:** `mainEntity` array of `Question` objects, each with `name` and `acceptedAnswer.text`
+- **Common errors:** marking up FAQs that aren't visibly Q&A on the page; using `Question` for content that is just an H2 + paragraph.
+- ⚠ **Note (2024–2026):** Google has significantly reduced FAQ rich-result eligibility — most sites no longer get FAQ rich results in SERPs. Apply this schema only to pages that are unambiguously Q&A (e.g., dedicated FAQ pages).
+
+### HowTo — **deprecated 2023-09**
+- Google fully retired HowTo rich results in September 2023 (mobile + desktop). The schema no longer drives any SERP feature for non-cooking content; cooking content should use `Recipe` instead.
+- **Do not generate `HowTo` markup as a rich-results play.** It can still ship for semantic clarity, but the rationale must say so explicitly — otherwise the user will assume rich-result eligibility that no longer exists.
+- For step-by-step content, prefer plain prose + numbered headings + `Article` schema.
+
+### BreadcrumbList
+- **Required:** `itemListElement` array (each with `position`, `name`, `item`)
+- **Recommended:** include the canonical absolute URL in each `item`.
+- **Note:** highly reliable rich result; most pages with breadcrumbs benefit.
+
+## Validation checklist (apply after generating)
+
+1. `@context` is exactly `https://schema.org` (lowercase, no trailing slash).
+2. `@type` matches one of the supported types above (case-sensitive).
+3. All URLs are **absolute**, not relative.
+4. Dates are ISO 8601 (`2026-04-27` or `2026-04-27T10:30:00+00:00`).
+5. The JSON parses cleanly (no trailing commas, balanced braces).
+6. The `<script type="application/ld+json">` block is in `<head>` or top of `<body>`.
+7. The structured data describes content **actually visible on the page**. Google penalises hidden-content schema.
+
+## When to skip generating
+
+- The page is a generic "kitchen sink" page that doesn't fit a single intent — generating speculative schema usually hurts.
+- The content is JS-rendered and the team doesn't server-side render — schema in client-only JS is often missed by crawlers.
+- The site is a low-trust domain Google has already penalised — schema doesn't unlock rich results until the trust signals improve.

package/skills/optbrew/modules/seranking-seo/skills/seo-schema/templates/article.json

@@ -0,0 +1,23 @@
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "{REPLACE: page title, max 110 chars}",
+  "description": "{REPLACE: meta description, ~155 chars}",
+  "author": {
+    "@type": "Person",
+    "name": "{REPLACE: author name}",
+    "url": "{REPLACE: author profile URL}"
+  },
+  "datePublished": "{REPLACE: ISO 8601 date, e.g. 2026-04-27}",
+  "dateModified": "{REPLACE: ISO 8601 date}",
+  "publisher": {
+    "@type": "Organization",
+    "name": "{REPLACE: brand name}",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "{REPLACE: logo URL, min 112x112px}"
+    }
+  },
+  "image": "{REPLACE: hero image URL, min 1200x800px}",
+  "mainEntityOfPage": "{REPLACE: canonical URL of this page}"
+}

package/skills/optbrew/modules/seranking-seo/skills/seo-schema/templates/breadcrumb-list.json

@@ -0,0 +1,18 @@
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {
+      "@type": "ListItem",
+      "position": 1,
+      "name": "{REPLACE: breadcrumb 1 label}",
+      "item": "{REPLACE: breadcrumb 1 URL}"
+    },
+    {
+      "@type": "ListItem",
+      "position": 2,
+      "name": "{REPLACE: breadcrumb 2 label}",
+      "item": "{REPLACE: breadcrumb 2 URL}"
+    }
+  ]
+}

package/skills/optbrew/modules/seranking-seo/skills/seo-schema/templates/faq-page.json

@@ -0,0 +1,22 @@
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "{REPLACE: question 1 — must be visibly on the page}",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "{REPLACE: answer 1 — must match the visible answer}"
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "{REPLACE: question 2}",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "{REPLACE: answer 2}"
+      }
+    }
+  ]
+}

package/skills/optbrew/modules/seranking-seo/skills/seo-schema/templates/local-business.json

@@ -0,0 +1,32 @@
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "@id": "{REPLACE: canonical URL}",
+  "name": "{REPLACE: business name}",
+  "description": "{REPLACE: short description}",
+  "url": "{REPLACE: website URL}",
+  "telephone": "{REPLACE: phone in international format, e.g. +14155550100}",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "{REPLACE: street}",
+    "addressLocality": "{REPLACE: city}",
+    "addressRegion": "{REPLACE: state/region}",
+    "postalCode": "{REPLACE: postal code}",
+    "addressCountry": "{REPLACE: ISO country code, e.g. US}"
+  },
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": "{REPLACE: latitude}",
+    "longitude": "{REPLACE: longitude}"
+  },
+  "openingHoursSpecification": [
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+      "opens": "09:00",
+      "closes": "17:00"
+    }
+  ],
+  "priceRange": "$$",
+  "image": "{REPLACE: storefront/exterior image URL}"
+}

package/skills/optbrew/modules/seranking-seo/skills/seo-schema/templates/product.json

@@ -0,0 +1,25 @@
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "{REPLACE: product name}",
+  "description": "{REPLACE: product description}",
+  "image": ["{REPLACE: product image URL}"],
+  "sku": "{REPLACE: SKU}",
+  "brand": {
+    "@type": "Brand",
+    "name": "{REPLACE: brand name}"
+  },
+  "offers": {
+    "@type": "Offer",
+    "url": "{REPLACE: product URL}",
+    "priceCurrency": "USD",
+    "price": "{REPLACE: price as STRING, e.g. \"49.00\"}",
+    "availability": "https://schema.org/InStock",
+    "itemCondition": "https://schema.org/NewCondition"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "{REPLACE: average rating as string, e.g. \"4.6\"}",
+    "reviewCount": "{REPLACE: total reviews as string}"
+  }
+}

package/skills/optbrew/modules/seranking-seo/skills/seo-sitemap/GUIDE.md

@@ -0,0 +1,128 @@
+> Example output: examples/seo-sitemap-notion-so-20260514/SITEMAP.md (upstream-only reference; route through optbrew)
+
+# Sitemap Analysis
+
+Compare a domain's XML sitemap against the most recent SE Ranking website audit. Surface what the sitemap claims vs what the crawler actually found, in both directions.
+
+## Prerequisites
+
+- SE Ranking MCP server connected.
+- Claude's `WebFetch` tool available.
+- User provides: a target domain. Optional: the sitemap URL if not at `/sitemap.xml` (auto-discovery from `robots.txt` is attempted first).
+- **Predecessor:** `seo-technical-audit` (or any prior SE Ranking audit) on this domain. Without an existing audit, this skill has nothing to compare against — chain `seo-technical-audit` first.
+
+## Process
+
+1. **Validate target & confirm audit**
+   - Normalise the domain.
+   - `DATA_listAudits` → confirm an audit exists for this domain. If none, surface a clear message: "Run `seo-technical-audit` first; this skill compares the sitemap to that audit's crawl."
+   - Use the most recent `done` audit by default.
+   - **Firecrawl availability check.** If `mcp__firecrawl-mcp__firecrawl_map` is available, Mode-2 (URL discovery via crawl) is offered when the sitemap is missing or suspect. Cost: ~0.5 Firecrawl credits per URL discovered, hard cap 500 URLs (~250 credits). Without Firecrawl, the skill runs Mode-1 only and notes the gap if Mode-2 was needed. User may pass `--no-firecrawl` to force Mode-1 even when Firecrawl is available (saves credits at the cost of orphan/missing analysis when sitemap is broken).
+
+2. **Build URL lists** `WebFetch` (sitemap) + `mcp__firecrawl-mcp__firecrawl_map` (optional Mode-2)
+   - **Mode-1 (default).** Try `https://{domain}/sitemap.xml`. If 404, fetch `/robots.txt` and look for `Sitemap:` directives. For sitemap-of-sitemaps, recursively fetch each child sitemap. Build the canonical URL list from the sitemap.
+   - **Mode-2 trigger.** Switch on Mode-2 when (a) no sitemap is reachable, (b) the sitemap returns < 10% of the audit's `DATA_getCrawledPages` count, or (c) the user explicitly requests `--discover`. Always surface the trigger and the cost estimate to the user before running Mode-2.
+   - **Mode-2 execution** (requires Firecrawl): call `firecrawl_map(url=domain, limit=500)`. The response is the URL list Firecrawl could discover from the homepage and internal linking. Use this list as the "sitemap-equivalent" in step 6 — the diffs run identically, just with discovered URLs in place of declared sitemap URLs.
+   - **If Mode-2 is needed but Firecrawl is unavailable:** continue with whatever sitemap data Mode-1 returned (possibly empty). Surface clearly in `SITEMAP.md`: `Mode-2 (Firecrawl URL discovery) needed but Firecrawl not installed — sitemap-vs-audit diffs run on partial data only.`
+
+3. **Pull the audit's crawled pages** `DATA_getCrawledPages`
+   - All URLs the crawler found, with status codes, indexability flags, depth.
+
+4. **Pull domain pages** `DATA_getDomainPages`
+   - Domain-level page inventory (broader than the audit's crawl scope in some cases).
+
+5. **Pull orphan-page issues** `DATA_getAuditPagesByIssue`
+   - Filter for orphan-page and depth-related issues. These intersect with sitemap analysis.
+
+6. **Compute the four diffs**
+   - **Missing from sitemap:** URLs in `DATA_getCrawledPages` (status 200, indexable) that don't appear in the sitemap. Probably should be added.
+   - **Orphans from sitemap:** URLs in the sitemap that the crawler didn't find via internal links (cross-ref `DATA_getAuditPagesByIssue` orphan flags). The sitemap is the only thing pointing at them — investigate whether they should be linked internally.
+   - **Broken sitemap entries:** sitemap URLs that returned non-200 in the audit's crawl. Remove from sitemap or fix the URL.
+   - **Lastmod issues:** sitemap entries where (a) all `<lastmod>` dates are identical (lazy generation) or (b) `<lastmod>` is older than the audit's crawl date for the page even though the page changed (stale).
+
+7. **Validation**
+   - URL count <50,000 per file (sitemap protocol limit). Flag if exceeded.
+   - Sitemap referenced in `robots.txt`.
+   - Encoding: each URL is XML-safe (ampersands escaped, etc.).
+   - HTTPS consistency: sitemap URLs match the canonical protocol.
+   - **`<lastmod>` is the only optional tag Google still consumes.** Validate it (step 6). `<priority>` and `<changefreq>` have been **explicitly ignored by Google for years** (per [Google's sitemap docs](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap) — "Google ignores `priority` and `changefreq` values"). Don't validate them; if present, flag as low-signal noise the user can strip to shrink the sitemap.
+
+8. **Synthesise** `SITEMAP.md`
+
+## Output format
+
+Create a folder `seo-sitemap-{target-slug}-{YYYYMMDD}/` with:
+
+```
+seo-sitemap-{target-slug}-{YYYYMMDD}/
+├── SITEMAP.md                       (synthesised report — primary deliverable)
+├── recommended-sitemap-diff.md      (proposed changes: add X, remove Y — load-bearing artefact engineering applies to sitemap.xml)
+└── evidence/
+    └── source-data.md               (consolidated raw step output: fetched sitemap content, Firecrawl-discovered URLs if Mode-2 ran, audit's crawled-pages list, the four diffs (missing/orphans/broken/lastmod-issues) — preserved for reproducibility)
+```
+
+Top-level: `SITEMAP.md` + `recommended-sitemap-diff.md`. The seven raw step files (`01-sitemap-raw`, `01b-firecrawl-discovered`, `02-audit-pages`, `03-missing-from-sitemap`, `04-orphans-from-sitemap`, `05-broken-entries`, `06-lastmod-issues`) are consolidated into a single `evidence/source-data.md` document with the same per-step section headers — a reader who needs to replay the diff has all raw inputs in one file rather than seven.
+
+`SITEMAP.md` follows this shape:
+
+```markdown
+# Sitemap Analysis: {domain}
+
+> Sitemap pulled {YYYY-MM-DD} · Audit reference {audit-date}
+
+## Mode
+
+- **Mode-1 (sitemap-vs-audit):** {ran / skipped — no sitemap reachable}
+- **Mode-2 (Firecrawl URL discovery):** {ran with {n} URLs / not triggered / triggered but Firecrawl not installed}
+
+## Health summary
+
+| Metric | Value | Status |
+|---|---|---|
+| Sitemap URLs (Mode-1) | {n} | — |
+| Discovered URLs (Mode-2, if ran) | {n} | — |
+| Audit crawled URLs (200, indexable) | {n} | — |
+| Missing from sitemap (probable adds) | {n} | {🔴 if >5%} |
+| Orphans from sitemap (probable cuts or link-ins) | {n} | {🟡 if >5} |
+| Broken sitemap entries (non-200) | {n} | {🔴 if >0} |
+| Lastmod issues | {n} | {🟡 if uniform; 🔴 if stale} |
+
+## Recommended changes
+
+### Add to sitemap ({n} URLs)
+- {URL} — found by crawler at depth {n}, status 200, indexable.
+- ...
+
+### Remove from sitemap ({n} URLs)
+- {URL} — returns {status code}.
+- ...
+
+### Investigate (orphan from sitemap, {n} URLs)
+- {URL} — in sitemap but not reachable via internal links. Either link from {suggested parent} or remove from sitemap.
+- ...
+
+### Fix lastmod ({n} URLs)
+- {URL} — lastmod is {date} but the audit crawled the page on {date} and detected changes since.
+- ...
+
+## Validation
+
+- Total URL count: {n} ({✓ under 50k limit | ✗ exceeds — split into sitemap-of-sitemaps})
+- Referenced in robots.txt: {✓/✗}
+- HTTPS consistency: {✓/✗}
+- Encoding: {✓/✗}
+
+## Apply
+- See `recommended-sitemap-diff.md` for the proposed sitemap.xml changes.
+- After applying, re-run `seo-technical-audit` to refresh the crawl, then re-run this skill to verify.
+```
+
+## Tips
+
+- Run `seo-technical-audit` first. Without an audit, this skill has nothing to compare.
+- Re-run after deploys that change page inventory (new content, removed pages, URL restructures).
+- Sitemap-of-sitemaps fan-out can be large for big sites — the skill recursively fetches all child sitemaps. For sites with 50+ child sitemaps, fetching dominates runtime; not credit cost.
+- `<priority>` and `<changefreq>` are dead signals — Google explicitly ignores both. Don't waste time tuning them; if your sitemap generator emits them, the bytes are pure overhead. `<lastmod>` is still consumed, so keep that one accurate.
+- The "investigate orphans" list is often the highest-leverage finding — pages that exist but aren't linked are usually accidentally orphaned, and adding a couple of internal links can revive them.
+- Pair with `seo-drift` to track sitemap composition over time (URL count, lastmod patterns).
+- Cost: ~5–10 SE Ranking credits typical (mostly the `getCrawledPages` and `getDomainPages` calls). Mode-2 adds Firecrawl credits at ~0.5 per discovered URL — surface the estimate before triggering.