@seoagent-official/seoagent 1.7.0

package/skills/references/programmatic.md

@@ -0,0 +1,155 @@
+# Programmatic SEO Protocol
+
+Programmatic SEO is template-driven scale: one template + a dataset → hundreds or thousands of pages targeting long-tail keyword variations. Done well, it captures real search demand at scale. Done badly, it's thin-content spam that gets penalized.
+
+## Core Rules (apply to every programmatic project)
+
+1. **Every page must provide unique value.** Just swapping `{city}` in a template is thin content. Each page needs at least one piece of data that *only* this page can show.
+2. **Proprietary data > public data.** "Best restaurants in {city}" using public Google data → already done. "Average response time of plumbers in {city}, based on our 50,000-job dataset" → unique.
+3. **Internal linking prevents orphaning.** Every programmatic page must link to at least 3 other programmatic pages in the same set + 1 hub page.
+4. **Match real search intent.** Run WebSearch on 5-10 sample queries before building. If the SERP is dominated by aggregators or directories, you may have a shot. If it's dominated by Wikipedia or government sites, skip.
+5. **Quality > quantity.** 200 great pages beat 5,000 thin ones. Google's site-quality signals are aggregated — thin programmatic pages drag down your whole domain.
+
+## The 12 Programmatic Playbooks
+
+### 1. Comparison Pages
+Pattern: `/{tool-a}-vs-{tool-b}` (e.g. `/notion-vs-airtable`)
+Data needed: features matrix, pricing, use cases, reviews per tool
+Search intent: high-intent, decision stage
+Word count: 1500-2500
+Schema: `Product` per tool + `ItemList` of comparison points
+Example: G2's comparison pages, Capterra, Webflow's "Webflow vs X" pages
+
+### 2. Alternative Pages
+Pattern: `/{tool}-alternatives` (e.g. `/zapier-alternatives`)
+Data needed: list of 5-15 alternatives with key differentiators per
+Search intent: competitor research
+Word count: 2000-3000
+Schema: `ItemList` with each alternative as a `Product`
+Critical: don't just list competitors; explain WHY someone should choose each one
+
+### 3. Use Case Pages
+Pattern: `/{tool}-for-{use-case}` (e.g. `/airtable-for-project-management`)
+Data needed: tool capabilities, use-case-specific workflow, sample template
+Search intent: evaluating fit
+Word count: 1200-1800
+Best when: you have a real example or template to share
+
+### 4. Integration Pages
+Pattern: `/integrations/{tool}` or `/{your-tool}-{their-tool}-integration`
+Data needed: setup steps, common workflows, example automations
+Search intent: people Google "{your tool} {other tool}" to verify integration exists
+Word count: 800-1200
+Schema: `HowTo` for the setup walkthrough
+Each integration needs: setup steps, common workflows, an FAQ on quirks
+
+### 5. Location Pages
+Pattern: `/{service}-{city}` or `/{tool}/cities/{city}`
+Data needed: location-specific stats, local examples, location-relevant pricing
+Search intent: local-intent searches ("plumber chicago")
+Word count: 600-1000
+Critical: needs Local Business schema with address, geo coordinates, hours
+Risk: highest spam risk — make sure each page genuinely has unique local content
+
+### 6. Industry / Persona Pages
+Pattern: `/for/{industry}` or `/{tool}-for-{persona}`
+Data needed: industry-specific use cases, customers in that vertical, ROI metrics specific to that vertical
+Search intent: SaaS evaluation by industry
+Word count: 1000-1500
+
+### 7. Glossary Entries
+Pattern: `/glossary/{term}` or `/{topic}/{term}`
+Data needed: clear definition, examples, related terms
+Search intent: informational, AI-search-friendly
+Word count: 400-800 (shorter than long_tails)
+Schema: `DefinedTerm` + `Article`
+Build at scale once: 50-100 terms in your domain's vocabulary
+
+### 8. Listing / Directory Pages
+Pattern: `/{category}/{location-or-attribute}` (e.g. `/best-{tool}-for-{use-case}`)
+Data needed: curated list of items with structured data per item
+Search intent: "best X" searches
+Word count: 1500-3000 (mostly structured)
+Schema: `ItemList`
+
+### 9. Calculator / Tool Pages
+Pattern: `/{topic}-calculator` or `/{tool}-calculator`
+Data needed: a working calculator + explanatory content
+Search intent: high — the calculator IS the value
+Word count: 600-1000 of explainer copy alongside the tool
+Best programmatic format: the tool itself is unique value per page
+
+### 10. Template / Example Pages
+Pattern: `/templates/{template-slug}`
+Data needed: a downloadable or copyable template + use case explanation
+Search intent: people Googling "{x} template"
+Word count: 500-1000
+Schema: `CreativeWork` or specific subtype
+
+### 11. Profile / Listing-of-Things Pages
+Pattern: `/companies/{company}` or `/people/{person}` or `/products/{product}`
+Data needed: structured profile with proprietary data
+Search intent: branded searches for individual entities
+Word count: 800-1500 with structured data carrying weight
+Schema: `Organization`, `Person`, or `Product` as appropriate
+
+### 12. Translated Pages
+Pattern: `/{lang}/{slug}` or subdomain
+Data needed: properly translated content (not machine-translated boilerplate)
+Search intent: language-specific search demand
+Critical: machine translation is detected by Google. Use professional translation or skip.
+Schema: hreflang tags + canonical
+
+## Choosing a Playbook
+
+Match the playbook to your assets:
+- **Have unique data?** → Listing pages (#8), Profile pages (#11), Comparison pages (#1)
+- **Have a tool?** → Calculator pages (#9), Integration pages (#4)
+- **Have customers in many segments?** → Industry pages (#6), Use case pages (#3)
+- **Have many integrations?** → Integration pages (#4)
+- **Have geographic relevance?** → Location pages (#5) (with caution)
+
+You can combine playbooks: comparison pages × industry → `/{tool-a}-vs-{tool-b}-for-{industry}`. Be selective — combinatorial explosions create thin content fast.
+
+## Implementation Framework
+
+1. **Keyword Pattern Research**
+   - Run WebSearch on 5-10 sample queries that fit the pattern
+   - Identify search volume signals (autocomplete, "people also ask")
+   - Confirm the SERP isn't dominated by Wikipedia or government sites
+2. **Data Source**
+   - Identify your data source. Is it proprietary? Public-but-aggregated? User-generated?
+   - Each page needs at least one *unique* data point
+3. **Template Design**
+   - Mock up the template with a real example. Is it 600+ words of actual content per page?
+   - Design the URL pattern. Flat is better than nested.
+4. **Internal Linking Strategy**
+   - Plan the hub page (a category index)
+   - Plan how programmatic pages link to each other (related, alternatives)
+5. **Build a Pilot Set**
+   - Build 10-20 pages first. Wait 4-8 weeks. Check rankings.
+   - If those rank, scale up. If they don't, diagnose before building 1,000.
+6. **Sitemap & Indexation**
+   - Submit programmatic pages in a separate sitemap so you can monitor indexation rate
+   - If <50% are indexed after 8 weeks, you have a quality problem — Google is rejecting them
+7. **Monitor and Prune**
+   - Pages ranking on positions 50+ after 6 months are dragging down site quality
+   - Either improve them or `noindex` them
+
+## When NOT to Build Programmatic
+
+- The SERP is owned by Wikipedia, government, or huge brands → skip
+- You don't have unique data → skip (or get unique data first)
+- Your dataset has gaps that produce empty/thin pages → tighten the dataset first
+- Your domain is new (< 6 months old) → focus on traditional content first
+
+## After Building
+
+1. Add a hub page that lists all programmatic pages with internal linking
+2. Submit a dedicated sitemap to Google Search Console
+3. Track indexation rate weekly for the first 8 weeks
+4. Persist the pattern to `.seoagent/strategy/clusters/programmatic-{pattern}.md` so the agent knows about it next session
+
+## Persistence
+
+Programmatic pages get saved to `.seoagent/content/programmatic/{slug}.md` with `page_type: programmatic`. The cluster file in `strategy/clusters/` tracks the pattern (template) and the URL list.

package/skills/references/rewrite-protocol.md

@@ -0,0 +1,163 @@
+# Rewrite & Refresh Protocol (Phase 4b)
+
+When to rewrite an existing article instead of writing a new one. The single most-asked feature in SEO content workflows: "update my existing post."
+
+## When to Rewrite
+
+Strong signals an article needs a refresh:
+
+1. **Stats / facts > 18 months old** — readers and search engines penalize stale data
+2. **Ranking dropped** — used to be on page 1, now on page 3+
+3. **Search intent shifted** — Google's SERP for the keyword now shows different content types
+4. **Competitor content is now stronger** — newer competitors cover what you missed
+5. **Cluster expanded** — new sub_pillars exist that the pillar should reference
+6. **Tone drift** — the article doesn't match the current `context.md` brand voice
+7. **User explicitly asks** — "rewrite this", "update this post", "refresh the homepage"
+
+If none of these are true: don't rewrite. Refreshing for the sake of it can hurt rankings (Google sees disruptive changes to ranking pages).
+
+## Procedure
+
+### Step 1: Identify the Target
+
+If the user gives a slug, file path, or URL:
+- Read `.seoagent/content/{slug}.md` if it's a SEOAgent-generated article
+- WebFetch the live URL if it's not in `.seoagent/`
+- If neither — ask the user where the source of truth is
+
+### Step 2: Read Context
+
+Before any edits, read:
+- `.seoagent/context.md` — current brand voice, banned topics, audience
+- `.seoagent/strategy/clusters/{cluster}.md` — the article's role and link graph
+- `.seoagent/briefs/{slug}.md` if it exists — the original brief
+
+### Step 3: Diagnose the Gaps
+
+Run a structured diagnosis. Use this exact template — output it to the user before editing:
+
+```markdown
+## 🔍 Refresh Diagnosis — {slug}
+
+### Stale Content
+- {stat or fact} — currently says "X (2024 data)", should be updated
+- {section} — references discontinued tool / outdated framework
+
+### Missing Coverage
+- New sub_pillar exists in cluster: {sub_pillar} — pillar should link to it
+- Top-3 competitor now covers {topic}; we don't
+
+### Structural Issues
+- {observation about hierarchy, AI extractability, etc.}
+
+### Tone & Voice
+- {observation if context.md has shifted since article was written}
+
+### What's Working (Preserve)
+- {section} ranks well; keep largely intact
+- {section} has good backlinks per current analysis
+
+## Plan (Y/N)
+1. Update {N} stats with 2026 figures
+2. Add new H2: "{section title}" linking to {sub_pillar}
+3. Tighten {section} — currently {old word count}, target {new word count}
+4. Refresh hero image alt text + add OG card
+```
+
+Wait for user confirmation before executing.
+
+### Step 4: Execute the Rewrite
+
+Rules:
+- **Preserve the URL slug.** Never change `slug` — even if the title changes, the URL stays.
+- **Preserve sections that rank.** If a section is the page's strongest signal, keep its core wording.
+- **Use `Edit`, not `Write`.** Edit one section at a time so changes are reviewable.
+- **Update `dateModified`** in JSON-LD. Don't change `datePublished` — that resets ranking signal.
+- **Bump `version`** in frontmatter (1 → 2 → 3).
+
+### Step 5: Update the Frontmatter
+
+```yaml
+---
+slug: tech-seo-guide
+page_type: pillar
+title: "The Complete Technical SEO Guide for 2026"   # year may update
+status: drafted
+created_at: 2024-01-15T10:00:00Z                     # NEVER change
+updated_at: 2026-04-27T10:00:00Z                     # update this
+version: 3                                            # bump
+word_count: 3450                                      # update if changed
+---
+```
+
+Add to JSON-LD:
+```json
+{
+  "@type": "Article",
+  "datePublished": "2024-01-15",
+  "dateModified": "2026-04-27"
+}
+```
+
+Both dates in the schema. Google uses `dateModified` to know freshness without resetting ranking signal.
+
+### Step 6: Update Internal Links
+
+If the rewrite added or changed internal links:
+- Update the cluster file's "Internal Linking" section
+- If you added a link DOWN to a sub_pillar, also add the reverse link UP from the sub_pillar (use `Edit`)
+
+### Step 7: Log and Sync
+
+Append to `.seoagent/changelog.md`:
+```
+[2026-04-27] Rewrote tech-seo-guide v3: updated 7 stats, added "AI Search Readiness" H2 linking to ai-search-readiness sub_pillar, tightened from 3120 → 3450 words
+```
+
+Run `seoagent sync`.
+
+## Special Cases
+
+### Rewriting a Landing Page
+
+Same protocol but:
+- Track conversion impact — note in changelog if there's a CRO concern
+- Don't ship the rewrite during a campaign in flight — coordinate with the user
+- Update OG card and Twitter card alt text (often forgotten)
+- Update JSON-LD `Product` / `Offer` if pricing or feature claims changed
+
+### Rewriting Without an Existing Brief
+
+If the article exists but `.seoagent/briefs/{slug}.md` does not:
+1. Generate a brief from the live article first (Phase 3 protocol)
+2. Show it to the user, confirm it represents the *intended* article
+3. Then rewrite against that brief
+
+This catches situations where the article drifted from any original spec.
+
+### "Annual Refresh" — Updating Year References
+
+If the user says "update for 2026" and only the year needs to change:
+1. Find every `2024`, `2025` reference in the article
+2. Update only the ones that genuinely refer to current-year data
+3. Update `dateModified` in JSON-LD
+4. Don't bump major version — this is a minor refresh
+
+Output a brief diff summary so the user can confirm nothing else changed.
+
+### Rewriting AI-Generated Content That Wasn't Yours
+
+If the user wants to rewrite a post that wasn't drafted with SEOAgent (no brief, no `.seoagent/content/{slug}.md`):
+1. WebFetch the live URL
+2. Save a copy to `.seoagent/content/{slug}.md` with `imported_at` in frontmatter
+3. Generate a brief representing the *current* article
+4. Then run the diagnosis (Step 3) and rewrite
+
+This brings the article into SEOAgent's persistence model so future refreshes have history.
+
+## Common Pitfalls
+
+- **Changing the URL.** Breaks backlinks, breaks rankings. Use a 301 redirect only if absolutely necessary, never silently.
+- **Resetting `datePublished`.** Tells Google "this is a new article" — kills accumulated ranking signal.
+- **Rewriting the entire article.** A 90% rewrite is a new article. If you're doing that, change the slug too — but accept the ranking reset.
+- **Forgetting the link graph.** A pillar rewrite without updating sub_pillar links creates broken hub-and-spoke structure.

package/skills/references/schema-markup.md

@@ -0,0 +1,297 @@
+# Schema Markup Library
+
+JSON-LD is the recommended format. Embed in `<script type="application/ld+json">` tags in `<head>`. The article frontmatter `json_ld` array becomes one or more `<script>` tags at render time.
+
+## Recommended Schema by Page Type
+
+| Page type | Required | Add when relevant |
+|---|---|---|
+| Pillar article | `Article` | `FAQPage`, `HowTo` |
+| Sub-pillar article | `Article` | `FAQPage`, `HowTo` |
+| Long-tail article | `Article` | `HowTo` |
+| Landing page (homepage / about) | `Organization` | `WebSite`, `BreadcrumbList` |
+| Landing page (pricing / product) | `Product` + `Offer` | `AggregateRating`, `Review` |
+| Landing page (SaaS feature) | `SoftwareApplication` | `Offer` |
+| FAQ page | `FAQPage` | — |
+| Glossary entry | `Article` + `DefinedTerm` | — |
+| Programmatic listing | `ItemList` | `Product`, `Organization`, `Place` per item |
+| Local business / location | `LocalBusiness` (or specific subtype) | `OpeningHoursSpecification`, `GeoCoordinates` |
+| Recipe (rare for SaaS — included for completeness) | `Recipe` | — |
+
+## Article Schema Templates
+
+### Article (default for blog content)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "The Complete Technical SEO Guide for 2026",
+  "author": {
+    "@type": "Person",
+    "name": "Jane Doe",
+    "url": "https://example.com/authors/jane"
+  },
+  "datePublished": "2026-04-27",
+  "dateModified": "2026-04-27",
+  "image": "https://example.com/blog/technical-seo-guide/hero.png",
+  "publisher": {
+    "@type": "Organization",
+    "name": "Acme",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "https://example.com/logo.png"
+    }
+  },
+  "mainEntityOfPage": "https://example.com/blog/technical-seo-guide"
+}
+```
+
+Required: `headline`, `author`, `datePublished`, `dateModified`, `image`, `publisher.logo`. Missing any of these and Google may reject the rich result.
+
+### FAQPage (add to articles with FAQ sections)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is technical SEO?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Technical SEO is the practice of optimizing a website's infrastructure so search engines can crawl, render, and index it efficiently. It covers crawlability, indexation, site speed, schema markup, and AI search readiness."
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "How is technical SEO different from on-page SEO?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Technical SEO covers infrastructure (crawl, render, index, speed). On-page SEO covers content and HTML structure (titles, meta, headings, keywords, internal links). Both matter; they target different layers."
+      }
+    }
+  ]
+}
+```
+
+The `Answer.text` should be the actual paragraph from the article — Google flags mismatches.
+
+### HowTo (add to step-by-step content)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "HowTo",
+  "name": "How to Submit a Sitemap to Google Search Console",
+  "description": "Step-by-step guide to submitting your sitemap.xml to Google Search Console.",
+  "totalTime": "PT5M",
+  "step": [
+    {
+      "@type": "HowToStep",
+      "name": "Open Google Search Console",
+      "text": "Sign in to Google Search Console at search.google.com/search-console.",
+      "url": "https://example.com/blog/submit-sitemap-gsc#step-1"
+    },
+    {
+      "@type": "HowToStep",
+      "name": "Navigate to Sitemaps",
+      "text": "In the left sidebar, click 'Sitemaps' under the 'Indexing' section.",
+      "url": "https://example.com/blog/submit-sitemap-gsc#step-2"
+    }
+  ]
+}
+```
+
+Each step's `url` should be a fragment link to that step's heading on the article page. Use anchor IDs.
+
+## Landing Page Schema Templates
+
+### Organization (homepage)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Acme",
+  "url": "https://acme.com",
+  "logo": "https://acme.com/logo.png",
+  "description": "Acme builds invoicing software for freelancers and small businesses.",
+  "foundingDate": "2024",
+  "sameAs": [
+    "https://twitter.com/acme",
+    "https://linkedin.com/company/acme",
+    "https://github.com/acme"
+  ],
+  "contactPoint": {
+    "@type": "ContactPoint",
+    "contactType": "customer support",
+    "email": "support@acme.com"
+  }
+}
+```
+
+### WebSite (homepage — for sitelinks search box)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  "url": "https://acme.com",
+  "potentialAction": {
+    "@type": "SearchAction",
+    "target": "https://acme.com/search?q={search_term_string}",
+    "query-input": "required name=search_term_string"
+  }
+}
+```
+
+### Product (pricing / product page)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Acme Pro",
+  "description": "...",
+  "brand": { "@type": "Brand", "name": "Acme" },
+  "offers": [
+    {
+      "@type": "Offer",
+      "name": "Starter",
+      "price": "29",
+      "priceCurrency": "USD",
+      "availability": "https://schema.org/InStock",
+      "url": "https://acme.com/pricing#starter"
+    },
+    {
+      "@type": "Offer",
+      "name": "Pro",
+      "price": "79",
+      "priceCurrency": "USD",
+      "availability": "https://schema.org/InStock",
+      "url": "https://acme.com/pricing#pro"
+    }
+  ],
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.8",
+    "reviewCount": "127"
+  }
+}
+```
+
+Only include `aggregateRating` if you have real review data — Google will manually penalize fake ratings.
+
+### SoftwareApplication (SaaS feature page)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Acme",
+  "applicationCategory": "BusinessApplication",
+  "operatingSystem": "Web",
+  "offers": {
+    "@type": "Offer",
+    "price": "29",
+    "priceCurrency": "USD"
+  }
+}
+```
+
+### LocalBusiness (location page)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "Acme Plumbing — Chicago",
+  "image": "https://acme.com/locations/chicago.jpg",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "123 Main St",
+    "addressLocality": "Chicago",
+    "addressRegion": "IL",
+    "postalCode": "60601",
+    "addressCountry": "US"
+  },
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": "41.8781",
+    "longitude": "-87.6298"
+  },
+  "telephone": "+1-555-0100",
+  "openingHoursSpecification": [
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+      "opens": "08:00",
+      "closes": "18:00"
+    }
+  ]
+}
+```
+
+Specific subtypes (`Restaurant`, `Plumber`, `Dentist`, etc.) win over generic `LocalBusiness` if your business fits one. See https://schema.org/LocalBusiness for the list.
+
+## Cross-Cutting Schemas
+
+### BreadcrumbList (every non-homepage page)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://acme.com" },
+    { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://acme.com/blog" },
+    { "@type": "ListItem", "position": 3, "name": "Technical SEO Guide", "item": "https://acme.com/blog/technical-seo-guide" }
+  ]
+}
+```
+
+### DefinedTerm (glossary entries)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "DefinedTerm",
+  "name": "Crawl Budget",
+  "description": "The number of pages a search engine crawler will fetch from a site within a given timeframe.",
+  "inDefinedTermSet": {
+    "@type": "DefinedTermSet",
+    "name": "Acme SEO Glossary"
+  },
+  "url": "https://acme.com/glossary/crawl-budget"
+}
+```
+
+## Validation
+
+Always tell users to test before deploying:
+- **Rich Results Test**: https://search.google.com/test/rich-results — checks if Google can parse the markup and which rich-result types it qualifies for
+- **Schema Validator**: https://validator.schema.org — checks pure schema.org compliance
+- Both tools accept either a URL or pasted code
+
+Common validation errors:
+- Missing required fields (`Article` requires `image`, `Product` requires `offers` with `price`)
+- Invalid date formats (use ISO 8601: `2026-04-27` or `2026-04-27T10:00:00Z`)
+- Wrong type for a field (`price` must be a string, not a number, in JSON-LD)
+- Mismatched content (FAQ schema's `Answer.text` doesn't match the visible page text)
+
+## When Multiple Schema Types Apply
+
+A pillar article with FAQs and step-by-step instructions can have all three:
+```yaml
+json_ld:
+  - "@type": Article
+    ...
+  - "@type": FAQPage
+    ...
+  - "@type": HowTo
+    ...
+```
+
+Each renders as a separate `<script type="application/ld+json">` tag. Multiple types on one page is supported and recommended.