optbrew 0.0.0-stage → 0.1.2

package/skills/optbrew/modules/marketing-search/skills/site-architecture/references/mermaid-templates.md

@@ -0,0 +1,216 @@
+# Mermaid Diagram Templates
+
+Copy-paste-ready Mermaid diagrams for visual sitemaps. Customize node labels and connections for your site.
+
+---
+
+## Basic Hierarchy
+
+Simple top-down page hierarchy.
+
+```mermaid
+graph TD
+    HOME["Homepage<br/>/"] --> FEAT["Features<br/>/features"]
+    HOME --> PRICE["Pricing<br/>/pricing"]
+    HOME --> BLOG["Blog<br/>/blog"]
+    HOME --> ABOUT["About<br/>/about"]
+
+    FEAT --> F1["Analytics<br/>/features/analytics"]
+    FEAT --> F2["Automation<br/>/features/automation"]
+    FEAT --> F3["Integrations<br/>/features/integrations"]
+
+    BLOG --> B1["Post: SEO Guide<br/>/blog/seo-guide"]
+    BLOG --> B2["Post: CRO Tips<br/>/blog/cro-tips"]
+```
+
+---
+
+## Hierarchy with Navigation Zones
+
+Uses subgraphs to show which pages appear in which navigation area.
+
+```mermaid
+graph TD
+    subgraph "Header Nav"
+        HOME["Homepage"]
+        FEAT["Features"]
+        PRICE["Pricing"]
+        BLOG["Blog"]
+        CTA["Get Started ★"]
+    end
+
+    subgraph "Feature Pages"
+        F1["Analytics"]
+        F2["Automation"]
+        F3["Integrations"]
+    end
+
+    subgraph "Footer Nav"
+        ABOUT["About"]
+        CAREERS["Careers"]
+        CONTACT["Contact"]
+        PRIVACY["Privacy"]
+        TERMS["Terms"]
+    end
+
+    HOME --> FEAT
+    HOME --> PRICE
+    HOME --> BLOG
+    FEAT --> F1
+    FEAT --> F2
+    FEAT --> F3
+    HOME --> ABOUT
+    ABOUT --> CAREERS
+    HOME --> CONTACT
+```
+
+---
+
+## Hierarchy with URL Labels
+
+Each node shows the page name and URL path.
+
+```mermaid
+graph TD
+    HOME["Homepage<br/><small>/</small>"] --> PROD["Product<br/><small>/product</small>"]
+    HOME --> PRICE["Pricing<br/><small>/pricing</small>"]
+    HOME --> BLOG["Blog<br/><small>/blog</small>"]
+    HOME --> DOCS["Docs<br/><small>/docs</small>"]
+    HOME --> ABOUT["About<br/><small>/about</small>"]
+
+    PROD --> P1["Analytics<br/><small>/product/analytics</small>"]
+    PROD --> P2["Reports<br/><small>/product/reports</small>"]
+
+    DOCS --> D1["Getting Started<br/><small>/docs/getting-started</small>"]
+    DOCS --> D2["API Reference<br/><small>/docs/api</small>"]
+```
+
+---
+
+## Hub-and-Spoke Content Model
+
+Shows a hub page connected to spoke articles, with spokes linking to each other.
+
+```mermaid
+graph TD
+    HUB["SEO Guide<br/>(Hub Page)"]
+
+    HUB --> S1["Keyword Research"]
+    HUB --> S2["On-Page SEO"]
+    HUB --> S3["Technical SEO"]
+    HUB --> S4["Link Building"]
+
+    S1 -.-> S2
+    S2 -.-> S3
+    S3 -.-> S4
+
+    style HUB fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+Legend:
+- Solid lines = primary hub-spoke links
+- Dashed lines = cross-links between spokes
+
+---
+
+## Internal Linking Flow
+
+Shows how different site sections link to each other.
+
+```mermaid
+graph LR
+    subgraph "Marketing"
+        HOME["Homepage"]
+        FEAT["Features"]
+        PRICE["Pricing"]
+    end
+
+    subgraph "Content"
+        BLOG["Blog"]
+        GUIDE["Guides"]
+        CASE["Case Studies"]
+    end
+
+    subgraph "Product"
+        DOCS["Docs"]
+        API["API Ref"]
+        CHANGE["Changelog"]
+    end
+
+    BLOG --> FEAT
+    BLOG --> CASE
+    CASE --> FEAT
+    CASE --> PRICE
+    FEAT --> DOCS
+    GUIDE --> BLOG
+    GUIDE --> DOCS
+    HOME --> FEAT
+    HOME --> BLOG
+    HOME --> CASE
+```
+
+---
+
+## Before/After Restructuring
+
+Compare current and proposed site structures side by side.
+
+```mermaid
+graph TD
+    subgraph "Before"
+        B_HOME["Homepage"] --> B_P1["Page 1"]
+        B_HOME --> B_P2["Page 2"]
+        B_HOME --> B_P3["Page 3"]
+        B_HOME --> B_P4["Page 4"]
+        B_HOME --> B_P5["Page 5"]
+        B_HOME --> B_P6["Page 6"]
+        B_HOME --> B_P7["Page 7"]
+        B_HOME --> B_P8["Page 8"]
+    end
+
+    subgraph "After"
+        A_HOME["Homepage"] --> A_S1["Features"]
+        A_HOME --> A_S2["Resources"]
+        A_HOME --> A_S3["Company"]
+        A_S1 --> A_P1["Feature A"]
+        A_S1 --> A_P2["Feature B"]
+        A_S2 --> A_P3["Blog"]
+        A_S2 --> A_P4["Guides"]
+        A_S3 --> A_P5["About"]
+        A_S3 --> A_P6["Contact"]
+    end
+```
+
+---
+
+## Color-Coding Conventions
+
+Use styles to highlight page status, priority, or type.
+
+```mermaid
+graph TD
+    HOME["Homepage"] --> FEAT["Features"]
+    HOME --> PRICE["Pricing"]
+    HOME --> BLOG["Blog"]
+    HOME --> NEW["New Section"]
+    HOME --> REMOVE["Deprecated Page"]
+
+    FEAT --> F1["Existing Feature"]
+    FEAT --> F2["New Feature"]
+
+    style HOME fill:#4CAF50,color:#fff
+    style PRICE fill:#4CAF50,color:#fff
+    style FEAT fill:#4CAF50,color:#fff
+    style BLOG fill:#4CAF50,color:#fff
+    style F1 fill:#4CAF50,color:#fff
+    style NEW fill:#2196F3,color:#fff
+    style F2 fill:#2196F3,color:#fff
+    style REMOVE fill:#f44336,color:#fff
+```
+
+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 or move
+- **Purple** (`#9C27B0`): High-priority / CTA pages

package/skills/optbrew/modules/marketing-search/skills/site-architecture/references/navigation-patterns.md

@@ -0,0 +1,305 @@
+# Navigation Patterns
+
+Detailed navigation patterns for different site types and contexts.
+
+---
+
+## Header Navigation
+
+### Simple Header (4-6 items)
+
+Best for: small businesses, simple SaaS, portfolios.
+
+```
+[Logo]   Features   Pricing   Blog   About   [CTA Button]
+```
+
+Rules:
+- Logo always links to homepage
+- CTA button is rightmost, visually distinct (filled button, contrasting color)
+- Items ordered by priority (most visited first)
+- Active page gets visual indicator (underline, bold, color)
+
+### Mega Menu Header
+
+Best for: SaaS with many features, e-commerce with categories, large content sites.
+
+```
+[Logo]   Product ▾   Solutions ▾   Resources ▾   Pricing   Docs   [CTA]
+```
+
+When "Product" is hovered/clicked:
+
+```
+┌─────────────────────────────────────────────────┐
+│  Features           Platform        Integrations │
+│  ─────────          ─────────       ──────────── │
+│  Analytics           Security       Slack         │
+│  Automation          API            HubSpot       │
+│  Reporting           Compliance     Salesforce    │
+│  Dashboards                         Zapier        │
+│                                                   │
+│  [See all features →]                             │
+└─────────────────────────────────────────────────┘
+```
+
+Mega menu rules:
+- 2-4 columns max
+- Group items logically (by feature area, use case, or audience)
+- Include a "See all" link at the bottom
+- Don't nest dropdowns inside mega menus
+- Show descriptions for items when labels alone aren't clear
+
+### Split Navigation
+
+Best for: apps with both marketing and product nav.
+
+```
+[Logo]   Features   Pricing   Blog        [Login]   [Sign Up]
+├── Marketing nav (left) ──────┘          └── Auth nav (right) ──┤
+```
+
+Right side handles authentication actions. Left side handles page navigation.
+
+---
+
+## Footer Navigation
+
+### Column-Based Footer (Standard)
+
+Best for: most sites. Organize links into 3-5 themed columns.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                                                          │
+│  Product          Resources        Company       Legal   │
+│  ─────────        ──────────       ─────────     ─────   │
+│  Features         Blog             About         Privacy │
+│  Pricing          Guides           Careers       Terms   │
+│  Integrations     Templates        Contact       GDPR    │
+│  Changelog        Case Studies     Press                 │
+│  Security         Webinars         Partners              │
+│                                                          │
+│  [Logo]  © 2026 Company Name                             │
+│  Social: [Twitter] [LinkedIn] [GitHub]                   │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Minimal Footer
+
+Best for: simple sites, landing pages.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  [Logo]                                                  │
+│  © 2026 Company  ·  Privacy  ·  Terms  ·  Contact        │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Expanded Footer
+
+Best for: sites using footer for SEO (comparison pages, location pages, resource links).
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Product     Resources    Compare         Use Cases      │
+│  Features    Blog         vs Competitor A  For Startups  │
+│  Pricing     Guides       vs Competitor B  For Enterprise│
+│  API         Templates    vs Competitor C  For Agencies  │
+│                                                          │
+│  Integrations             Popular Posts                  │
+│  Slack       Zapier       How to Do X                    │
+│  HubSpot     Salesforce   Guide to Y                     │
+│                           Template: Z                    │
+│                                                          │
+│  [Logo]  © 2026  ·  Privacy  ·  Terms  ·  Security      │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Sidebar Navigation
+
+### Documentation Sidebar
+
+Persistent left sidebar with collapsible sections.
+
+```
+Getting Started
+  ├── Installation
+  ├── Quick Start
+  └── Configuration
+
+Guides
+  ├── Authentication
+  ├── Data Models
+  └── Deployment
+
+API Reference
+  ├── REST API
+  │   ├── Users
+  │   ├── Projects
+  │   └── Webhooks
+  └── GraphQL
+
+Examples
+  ├── Next.js
+  ├── Rails
+  └── Python
+
+Changelog
+```
+
+Rules:
+- Current page highlighted
+- Sections collapsible (expanded by default for active section)
+- Search at top of sidebar
+- "Previous / Next" page navigation at bottom of content area
+- Sticky on scroll (doesn't scroll away)
+
+### Blog Category Sidebar
+
+```
+Categories
+  ├── SEO (24)
+  ├── CRO (18)
+  ├── Content (15)
+  ├── Paid Ads (12)
+  └── Analytics (9)
+
+Popular Posts
+  ├── How to Improve SEO
+  ├── Landing Page Guide
+  └── Analytics Setup
+
+Newsletter
+  └── [Email signup form]
+```
+
+---
+
+## Breadcrumbs
+
+### Standard Format
+
+```
+Home > Features > Analytics
+Home > Blog > SEO Category > How to Do Keyword Research
+Home > Docs > API Reference > Authentication
+```
+
+Rules:
+- Separator: `>` or `/` (be consistent)
+- Every segment is a link except the current page
+- Current page is plain text (not linked)
+- Don't include the current page if the title is already visible as an H1
+
+### With Schema Markup
+
+```html
+<nav aria-label="Breadcrumb">
+  <ol itemscope itemtype="https://schema.org/BreadcrumbList">
+    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
+      <a itemprop="item" href="/"><span itemprop="name">Home</span></a>
+      <meta itemprop="position" content="1" />
+    </li>
+    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
+      <a itemprop="item" href="/features"><span itemprop="name">Features</span></a>
+      <meta itemprop="position" content="2" />
+    </li>
+    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
+      <span itemprop="name">Analytics</span>
+      <meta itemprop="position" content="3" />
+    </li>
+  </ol>
+</nav>
+```
+
+Or use JSON-LD (recommended):
+
+```json
+{
+  "@context": "https://schema.org",
+  "@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" }
+  ]
+}
+```
+
+---
+
+## Mobile Navigation
+
+### Hamburger Menu
+
+Standard for mobile. All nav items collapse into a menu icon.
+
+Rules:
+- Hamburger icon (three lines) top-right or top-left
+- Full-screen or slide-out panel
+- CTA button visible without opening the menu (sticky header)
+- Search accessible from mobile menu
+- Accordion pattern for nested items
+
+### Bottom Tab Bar
+
+Best for: web apps, PWAs, mobile-first products.
+
+```
+┌──────────────────────────────────────┐
+│                                      │
+│           [Page Content]             │
+│                                      │
+├──────────────────────────────────────┤
+│  Home    Search    Create    Profile │
+│   🏠       🔍        ➕       👤    │
+└──────────────────────────────────────┘
+```
+
+Rules:
+- 3-5 items max
+- Icons + labels (not just icons)
+- Active state clearly indicated
+- Most important action in the center
+
+---
+
+## Anti-Patterns
+
+### Things to Avoid
+
+- **Too many header items** (8+): causes decision paralysis, nav becomes unreadable on smaller screens
+- **Dropdown inception**: dropdowns inside dropdowns inside dropdowns
+- **Mystery icons**: icons without labels — users don't know what they mean
+- **Hidden primary nav**: burying important pages in hamburger menus on desktop
+- **Inconsistent nav between pages**: nav should be identical across the site (except app vs marketing)
+- **No mobile consideration**: desktop nav that doesn't translate to mobile
+- **Footer as sitemap dump**: 50+ links in the footer with no organization
+- **Breadcrumbs that don't match URLs**: breadcrumb says "Products > Widget" but URL is `/shop/widget-pro`
+
+### Common Fixes
+
+| Problem | Fix |
+|---------|-----|
+| Too many nav items | Group into dropdowns or mega menus |
+| Users can't find pages | Add search, improve labeling |
+| High bounce from nav | Simplify choices, use clearer labels |
+| SEO pages not linked | Add to footer or resource sections |
+| Mobile nav is broken | Test on real devices, use hamburger pattern |
+
+---
+
+## Navigation for SEO
+
+Internal links in navigation pass PageRank. Use this strategically:
+
+- **Header nav links are strongest** — put your most important pages here
+- **Footer links pass less value** but still matter — good for comparison pages, location pages
+- **Sidebar links** help with section-level authority — good for blog categories, doc sections
+- **Breadcrumbs** provide structural signals to search engines — implement with schema markup
+- **Don't use JavaScript-only nav** — search engines need crawlable HTML links
+- **Use descriptive anchor text** — "Analytics Features" not just "Features"