@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/seo-audit/references/architecture-patterns.md

@@ -0,0 +1,271 @@
+# Architecture Patterns
+
+Site type templates, URL patterns, and navigation specs for common website types.
+
+---
+
+## SaaS Marketing Site
+
+### Page Hierarchy
+
+```
+Homepage (/)
+├── Features (/features)
+│   ├── Feature A (/features/feature-a)
+│   ├── Feature B (/features/feature-b)
+│   └── Feature C (/features/feature-c)
+├── Pricing (/pricing)
+├── Customers (/customers)
+│   ├── Case Study 1 (/customers/company-name)
+│   └── Case Study 2 (/customers/company-name-2)
+├── Resources (/resources)
+│   ├── Blog (/blog)
+│   │   └── [Posts] (/blog/post-slug)
+│   ├── Templates (/resources/templates)
+│   └── Guides (/resources/guides)
+├── Integrations (/integrations)
+│   └── [Integration] (/integrations/integration-name)
+├── Docs (/docs)
+│   ├── Getting Started (/docs/getting-started)
+│   └── API Reference (/docs/api)
+├── About (/about)
+│   ├── Careers (/about/careers)
+│   └── Contact (/contact)
+├── Compare (/compare)
+│   └── [Competitor] (/compare/competitor-name)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+**Header (6 items + CTA)**: Features | Pricing | Customers | Resources | Integrations | Docs | [Get Started]
+
+**Footer columns**: Product, Resources, Company, Legal
+
+---
+
+## Content / Blog Site
+
+```
+Homepage (/)
+├── Blog (/blog)
+│   ├── [Category] (/blog/category/topic-slug)
+│   └── [Posts] (/blog/post-slug)
+├── Newsletter (/newsletter)
+├── Resources (/resources)
+│   ├── Guides (/resources/guides)
+│   └── Tools (/resources/tools)
+├── About (/about)
+├── Contact (/contact)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+**Header (4 items + CTA)**: Blog | Resources | About | Contact | [Subscribe]
+
+**Sidebar** (on blog): Categories, Popular Posts, Newsletter signup
+
+---
+
+## E-Commerce
+
+```
+Homepage (/)
+├── Shop (/shop)
+│   ├── Category A (/shop/category-a)
+│   │   ├── Subcategory (/shop/category-a/subcategory)
+│   │   │   └── [Product] (/shop/category-a/subcategory/product-slug)
+│   │   └── [Product] (/shop/category-a/product-slug)
+│   └── Category B (/shop/category-b)
+├── Collections (/collections)
+├── Sale (/sale)
+├── Blog (/blog)
+├── Help (/help)
+│   ├── FAQ (/help/faq)
+│   ├── Shipping (/help/shipping)
+│   └── Returns (/help/returns)
+├── Cart (/cart)
+├── Account (/account)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+**Header (5 items + cart/account)**: Shop (mega menu) | Collections | Sale | Blog | Help | [Cart] [Account]
+
+---
+
+## Documentation Site
+
+```
+Docs Home (/docs)
+├── Getting Started (/docs/getting-started)
+│   ├── Installation (/docs/getting-started/installation)
+│   ├── Quick Start (/docs/getting-started/quick-start)
+│   └── Configuration (/docs/getting-started/configuration)
+├── Guides (/docs/guides)
+├── API Reference (/docs/api)
+├── Examples (/docs/examples)
+├── Changelog (/docs/changelog)
+└── FAQ (/docs/faq)
+```
+
+**Sidebar** (persistent, left): Getting Started, Guides, API Reference, Examples, Changelog
+
+**On-page**: Previous/Next navigation at bottom of each doc page
+
+---
+
+## Hybrid SaaS + Content
+
+```
+Homepage (/)
+├── Product (/product)
+│   ├── Feature A (/product/feature-a)
+│   └── Feature B (/product/feature-b)
+├── Solutions (/solutions)
+│   ├── By Use Case (/solutions/use-case-slug)
+│   └── By Industry (/solutions/industry-slug)
+├── Pricing (/pricing)
+├── Blog (/blog)
+├── Resources (/resources)
+│   ├── Guides, Templates, Webinars, Case Studies
+├── Docs (/docs)
+├── Integrations (/integrations)
+├── Compare (/compare)
+├── About (/about)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+**Header (7 items + CTA)**: Product | Solutions | Pricing | Resources | Blog | Docs | Integrations | [Start Free Trial]
+
+Use mega menus for Product, Solutions, and Resources.
+
+---
+
+## Small Business / Local
+
+```
+Homepage (/)
+├── Services (/services)
+│   ├── Service A (/services/service-a)
+│   └── Service B (/services/service-b)
+├── About (/about)
+├── Testimonials (/testimonials)
+├── Blog (/blog)
+├── Contact (/contact)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+**Header (5 items + CTA)**: Services | About | Testimonials | Blog | [Contact Us]
+
+Keep flat (1-2 levels max). Every page reachable from header.
+
+---
+
+## Navigation Rules
+
+### Header
+- 4-7 items max (decision paralysis above that)
+- CTA button rightmost, visually distinct
+- Logo links to homepage (left side)
+- Order by priority: most visited first
+
+### Footer
+Group into columns: Product, Resources, Company, Legal
+
+### Breadcrumbs
+```
+Home > Features > Analytics
+Home > Blog > SEO Category > Post Title
+```
+Mirror the URL hierarchy. Every segment clickable except current page.
+
+### Mobile
+- Hamburger menu for all nav items
+- CTA visible without opening menu (sticky header)
+- Accordion pattern for nested items
+
+---
+
+## URL Patterns by Page Type
+
+| Page Type | Pattern | Example |
+|-----------|---------|---------|
+| Homepage | `/` | `example.com` |
+| Feature page | `/features/{name}` | `/features/analytics` |
+| Blog post | `/blog/{slug}` | `/blog/seo-guide` |
+| Blog category | `/blog/category/{slug}` | `/blog/category/seo` |
+| Case study | `/customers/{slug}` | `/customers/acme-corp` |
+| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` |
+| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial` |
+| Comparison | `/compare/{competitor}` | `/compare/competitor-name` |
+| Integration | `/integrations/{name}` | `/integrations/slack` |
+
+### Common Mistakes
+- Dates in blog URLs (adds no value)
+- Over-nesting beyond 3 levels
+- Changing URLs without 301 redirects
+- IDs instead of slugs in URLs
+- Inconsistent parent patterns
+
+---
+
+## Internal Linking
+
+### Hub-and-Spoke Model
+```
+Hub: /blog/seo-guide (comprehensive overview)
+├── Spoke: /blog/keyword-research (links back to hub)
+├── Spoke: /blog/on-page-seo (links back to hub)
+├── Spoke: /blog/technical-seo (links back to hub)
+└── Spoke: /blog/link-building (links back to hub)
+```
+
+### Rules
+- No orphan pages (every page needs at least one inbound internal link)
+- Descriptive anchor text ("analytics features" not "click here")
+- 5-10 internal links per 1000 words
+- Link to important pages more often
+- Cross-section links: features to case studies, blog to product pages
+
+---
+
+## Mermaid Templates
+
+### Basic Hierarchy
+```mermaid
+graph TD
+    HOME["Homepage"] --> FEAT["Features"]
+    HOME --> PRICE["Pricing"]
+    HOME --> BLOG["Blog"]
+    HOME --> ABOUT["About"]
+    FEAT --> F1["Analytics"]
+    FEAT --> F2["Automation"]
+```
+
+### With Navigation Zones
+```mermaid
+graph TD
+    subgraph "Header Nav"
+        HOME["Homepage"]
+        FEAT["Features"]
+        PRICE["Pricing"]
+        BLOG["Blog"]
+        CTA["Get Started"]
+    end
+    subgraph "Footer Nav"
+        ABOUT["About"]
+        CONTACT["Contact"]
+        PRIVACY["Privacy"]
+    end
+    HOME --> FEAT
+    HOME --> PRICE
+    HOME --> BLOG
+```
+
+### Color Key
+- Green (`#4CAF50`): Existing pages (no changes)
+- Blue (`#2196F3`): New pages to create
+- Red (`#f44336`): Pages to remove or redirect
+- Yellow (`#FFC107`): Pages to restructure

package/skills/seo-audit/references/schema-templates.md

@@ -0,0 +1,427 @@
+# Schema Templates
+
+Complete JSON-LD examples for common schema types. Copy and customize for your site.
+
+## Schema Requirements by Page Type
+
+Use this table to know which schemas a page MUST emit before passing audit. Required = audit fails without it; Recommended = audit warns but doesn't fail.
+
+| Page type | Required | Recommended |
+|---|---|---|
+| Homepage | `SoftwareApplication` (SaaS) or `Product` (ecommerce), `Organization` | `WebSite` with `SearchAction` |
+| `/about` | `Organization`, `BreadcrumbList` | — |
+| `/pricing` | `Product` or `SoftwareApplication` with `offers` (Offer[]), `BreadcrumbList` | `FAQPage` (pricing questions) |
+| `/alternatives/[competitor]` | `SoftwareApplication`, `BreadcrumbList`, `FAQPage` | `Review` (with `reviewBody` for the honesty section) |
+| `/compare/[a]-vs-[b]` | `BreadcrumbList`, `FAQPage` | `Article` (with `author` + `dateModified`) |
+| `/for/[use-case]` or `/for/[audience]` | `SoftwareApplication`, `BreadcrumbList`, `FAQPage` | `Service` (if the use-case maps to a distinct offering) |
+| `/playbooks/[topic]` (long-form 2,500+ words) | `Article`, `BreadcrumbList` | `HowTo` (if step-based), `mentions` (entities) |
+| `/blog/[slug]` | `Article`, `BreadcrumbList` | `author` block with `Person`, `mentions` |
+| `/tools/[slug]` (free utility) | `SoftwareApplication` or `WebApplication`, `BreadcrumbList` | `FAQPage` |
+| `/case-studies/[slug]` | `Article` (or `Review`), `BreadcrumbList` | `Organization` (client) |
+| `/features/[slug]` | `SoftwareApplication`, `BreadcrumbList` | `FAQPage` |
+
+**Common mistakes the audit catches:**
+- Multiple `@type` values when one is required (e.g. `["Article", "BlogPosting"]` — pick one)
+- `FAQPage` without `mainEntity.acceptedAnswer.text` populated
+- `BreadcrumbList` missing `position` on items (Google ignores without it)
+- `SoftwareApplication` without `applicationCategory` (required field, often forgotten)
+- `Product` without `offers.priceCurrency` (price defaults to USD silently if omitted)
+- Future-dated `datePublished` (Google flags as untrustworthy)
+- `Article` `dateModified` < `datePublished` (logically inconsistent)
+
+**Per-page-type implementation** is in the individual sections below.
+
+---
+
+## Organization
+
+For company/brand homepage or about page.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Example Company",
+  "url": "https://example.com",
+  "logo": "https://example.com/logo.png",
+  "sameAs": [
+    "https://twitter.com/example",
+    "https://linkedin.com/company/example"
+  ],
+  "contactPoint": {
+    "@type": "ContactPoint",
+    "telephone": "+1-555-555-5555",
+    "contactType": "customer service"
+  }
+}
+```
+
+---
+
+## WebSite (with SearchAction)
+
+For homepage. Enables 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"
+  }
+}
+```
+
+---
+
+## Article / BlogPosting
+
+For blog posts and news articles.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "How to Implement Schema Markup",
+  "image": "https://example.com/image.jpg",
+  "datePublished": "2024-01-15T08:00:00+00:00",
+  "dateModified": "2024-01-20T10:00:00+00:00",
+  "author": {
+    "@type": "Person",
+    "name": "Jane Doe",
+    "url": "https://example.com/authors/jane"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Example Company",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "https://example.com/logo.png"
+    }
+  },
+  "description": "A complete guide to implementing schema markup...",
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://example.com/schema-guide"
+  }
+}
+```
+
+---
+
+## Product
+
+For product pages (e-commerce or SaaS).
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Premium Widget",
+  "image": "https://example.com/widget.jpg",
+  "description": "Our best-selling widget for professionals",
+  "sku": "WIDGET-001",
+  "brand": {
+    "@type": "Brand",
+    "name": "Example Co"
+  },
+  "offers": {
+    "@type": "Offer",
+    "url": "https://example.com/products/widget",
+    "priceCurrency": "USD",
+    "price": "99.99",
+    "availability": "https://schema.org/InStock",
+    "priceValidUntil": "2024-12-31"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.8",
+    "reviewCount": "127"
+  }
+}
+```
+
+---
+
+## SoftwareApplication
+
+For SaaS product pages and app landing pages.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Example App",
+  "applicationCategory": "BusinessApplication",
+  "operatingSystem": "Web, iOS, Android",
+  "offers": {
+    "@type": "Offer",
+    "price": "0",
+    "priceCurrency": "USD"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.6",
+    "ratingCount": "1250"
+  }
+}
+```
+
+---
+
+## FAQPage
+
+For pages with frequently asked questions.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is schema markup?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Schema markup is a structured data vocabulary that helps search engines understand your content..."
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "How do I implement schema?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "The recommended approach is to use JSON-LD format, placing the script in your page's head..."
+      }
+    }
+  ]
+}
+```
+
+---
+
+## HowTo
+
+For instructional content and tutorials.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "HowTo",
+  "name": "How to Add Schema Markup to Your Website",
+  "description": "A step-by-step guide to implementing JSON-LD schema",
+  "totalTime": "PT15M",
+  "step": [
+    {
+      "@type": "HowToStep",
+      "name": "Choose your schema type",
+      "text": "Identify the appropriate schema type for your page content..."
+    },
+    {
+      "@type": "HowToStep",
+      "name": "Write the JSON-LD",
+      "text": "Create the JSON-LD markup following schema.org specifications..."
+    },
+    {
+      "@type": "HowToStep",
+      "name": "Add to your page",
+      "text": "Insert the script tag in your page's head section..."
+    }
+  ]
+}
+```
+
+---
+
+## BreadcrumbList
+
+For any page with breadcrumb navigation.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://example.com"
+    },
+    {
+      "@type": "ListItem",
+      "position": 2,
+      "name": "Blog",
+      "item": "https://example.com/blog"
+    },
+    {
+      "@type": "ListItem",
+      "position": 3,
+      "name": "SEO Guide",
+      "item": "https://example.com/blog/seo-guide"
+    }
+  ]
+}
+```
+
+---
+
+## LocalBusiness
+
+For local business location pages.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "Example Coffee Shop",
+  "image": "https://example.com/shop.jpg",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "123 Main Street",
+    "addressLocality": "San Francisco",
+    "addressRegion": "CA",
+    "postalCode": "94102",
+    "addressCountry": "US"
+  },
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": "37.7749",
+    "longitude": "-122.4194"
+  },
+  "telephone": "+1-555-555-5555",
+  "openingHoursSpecification": [
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+      "opens": "08:00",
+      "closes": "18:00"
+    }
+  ],
+  "priceRange": "$$"
+}
+```
+
+---
+
+## Event
+
+For event pages, webinars, conferences.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Event",
+  "name": "Annual Marketing Conference",
+  "startDate": "2024-06-15T09:00:00-07:00",
+  "endDate": "2024-06-15T17:00:00-07:00",
+  "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
+  "eventStatus": "https://schema.org/EventScheduled",
+  "location": {
+    "@type": "VirtualLocation",
+    "url": "https://example.com/conference"
+  },
+  "description": "Join us for our annual marketing conference...",
+  "offers": {
+    "@type": "Offer",
+    "url": "https://example.com/conference/tickets",
+    "price": "199",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock"
+  },
+  "organizer": {
+    "@type": "Organization",
+    "name": "Example Company",
+    "url": "https://example.com"
+  }
+}
+```
+
+---
+
+## Multiple Schema Types with @graph
+
+Combine multiple schema types on one page.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "Organization",
+      "@id": "https://example.com/#organization",
+      "name": "Example Company",
+      "url": "https://example.com"
+    },
+    {
+      "@type": "WebSite",
+      "@id": "https://example.com/#website",
+      "url": "https://example.com",
+      "name": "Example",
+      "publisher": {
+        "@id": "https://example.com/#organization"
+      }
+    },
+    {
+      "@type": "BreadcrumbList",
+      "itemListElement": [
+        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
+        { "@type": "ListItem", "position": 2, "name": "Features", "item": "https://example.com/features" },
+        { "@type": "ListItem", "position": 3, "name": "Analytics" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Implementation (Next.js)
+
+```jsx
+export default function ProductPage({ product }) {
+  const schema = {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    name: product.name,
+    image: product.image,
+    offers: {
+      "@type": "Offer",
+      price: product.price,
+      priceCurrency: "USD",
+      availability: "https://schema.org/InStock"
+    }
+  };
+
+  return (
+    <>
+      <Head>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+        />
+      </Head>
+      {/* Page content */}
+    </>
+  );
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Validates in Google Rich Results Test (renders JavaScript)
+- [ ] No errors in Schema.org Validator
+- [ ] Schema matches visible page content
+- [ ] All required properties present
+- [ ] URLs are fully qualified (not relative)
+- [ ] Dates in ISO 8601 format
+- [ ] Monitor Search Console Enhancements reports after deployment