@stacksjs/defaults 0.75.109 → 0.75.110

package/ai/skills/stacks-marketing-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/ai/skills/stacks-marketing-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"

package/ai/skills/stacks-marketing-site-architecture/references/platforms-and-migration.md

@@ -0,0 +1,86 @@
+# Platforms and Migration
+
+Where the site gets built, how new pages join an existing site, and how to move platforms without losing search traffic. Load this when the user asks which builder or CMS to use, wants to add a section or landing pages to an existing site, or is planning a migration.
+
+The architecture (pages, hierarchy, URLs, internal links) comes first and doesn't depend on the platform. Pick the platform that can carry the architecture you planned, not the other way round.
+
+## Contents
+- Choosing Where to Build
+- The Options
+- Adding Pages to an Existing Site
+- Migrating Without Losing Traffic
+
+---
+
+## Choosing Where to Build
+
+Ask these before naming any platform. The answers usually narrow the field to two or three.
+
+1. **Who edits the site after launch?** A designer, a marketer who never touches code, an engineer, or an AI agent? The best platform for a designer-owned site is rarely the best for an engineer-owned one.
+2. **What does the site have to do?** A marketing site, a blog or resource library, pages at scale from data, a store, logged-in product screens? Marketing builders handle the first three; stores and apps usually belong elsewhere and get linked or proxied.
+3. **How many pages, and from what data?** A few dozen hand-built pages suit almost anything. Hundreds or thousands of templated pages need a CMS or database with the item limits to match (see the `stacks-marketing-programmatic-seo` skill's platform reference).
+4. **What has to connect?** CRM, forms, analytics, scheduling, ad pixels, the product's own login. Check the integrations that matter before falling for the editor.
+5. **How much lock-in is acceptable?** Can you export the code and content and host it elsewhere? Hosted builders trade portability for convenience.
+6. **What does it cost at the real size?** Per-site, per-seat, per-CMS-item, and usage-based pricing diverge fast as a site grows. Price the plan you'll need in a year.
+
+## The Options
+
+Characterizations as of 2026-10; check current plans and limits before committing.
+
+| Option | What it is | Good fit | Watch out for |
+|---|---|---|---|
+| **Webflow** | Mature visual builder and CMS with hosting | Designer-owned marketing sites, rich CMS-driven content, sites that need fine visual control | CMS item limits by plan; ecommerce and localization are add-ons; designer skill needed to keep it clean |
+| **Framer** | Design-led visual builder with CMS and fast publishing | Polished marketing sites and launches owned by designers or marketers | CMS item limits vary by plan (higher tiers reach tens of thousands); check the integrations you need |
+| **WordPress** | Open-source CMS with the largest plugin ecosystem; self-hosted or managed | Content-heavy sites, full ownership, teams with WordPress experience, budgets that favor licensing over build time | Plugin sprawl, security and update upkeep, performance depends on hosting and theme |
+| **Wix Studio, Squarespace** | All-in-one templated builders with built-in business apps | Small businesses and agencies that want hosting, commerce, and booking in one place | Less control over code and structure; harder to migrate off |
+| **Landing-page tools** (Unbounce, Instapage, Leadpages) | Builders for campaign pages, usually with A/B testing; Leadpages also builds full multi-page small-business sites | Paid-traffic landing pages; small sites on Leadpages | Unbounce and Instapage pages usually live on a subdomain or separate system rather than hosting the whole site |
+| **AI-native site platforms** (Ploy ◆, Flint, and similar) | Hosted builders where an AI agent builds, edits, and operates the site through conversation | Teams that want an agent to build and keep improving marketing pages, often alongside an existing site via path routing | Young products; hosting tied to the vendor; check export and code access before committing |
+| **AI app builders** (Lovable, v0, Bolt) | Prompt-to-app generators that output code | Prototypes, product UIs, and interactive tools | Built for apps more than marketing sites; CMS, SEO, and editing by non-engineers need extra work |
+| **Hand-coded** (Next.js, Astro, and similar on Vercel, Netlify, or Cloudflare) | Your own codebase and hosting | Full control and portability, engineer-owned sites, sites tightly coupled to the product | Every change needs an engineer unless you add a headless CMS; you own performance and SEO basics |
+| **Headless CMS + framework** (Sanity, Contentful, Storyblok with a hand-coded front end) | Content in a CMS, presentation in code | Large content operations with engineering support and multiple front ends | Two systems to run; marketers depend on engineers for new page types |
+
+◆ marks a [Verified Partner](https://github.com/coreyhaines31/marketingskills/blob/1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff/tools/REGISTRY.md#verified-partners) of this repository: disclosure, not endorsement. When you name a ◆ tool in an answer, say it's a Verified Partner of the repository this skill comes from, and name an alternative alongside it. Details for Ploy are in its [integration guide](https://github.com/coreyhaines31/marketingskills/blob/1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff/tools/integrations/ploy.md).
+
+**There's rarely one right answer.** Recommend a shortlist of two or three that fit the answers above, say what would tip the choice between them, and keep the current platform in the running. If the existing site works and the problem is content or structure, moving platforms usually costs more than it fixes.
+
+## Adding Pages to an Existing Site
+
+Often the job isn't a new site; it's a new section (a blog, landing pages, a resource library, pages at scale) on a site that already exists. Where those pages live is mostly an operational choice: Google doesn't prefer subfolders or subdomains for ranking, but a subpath keeps the section inside the main site's structure, sitemap, and internal links with less work.
+
+| Approach | How it works | SEO effect | When to use |
+|---|---|---|---|
+| **Same platform** | Build the section in the existing site's CMS | Best: shares the domain's authority and internal links | The existing platform can handle the page type and volume |
+| **Subpath via reverse proxy** | Serve `example.com/blog` from another system through a proxy or edge router (Cloudflare Workers, Vercel or Netlify rewrites, Nginx, or a platform's own routing rules) | Behaves like same-platform pages, as long as they're fully rendered, canonical to the main domain, and linked from it | A different tool is better for the section, and you want it to share the main domain's structure and links |
+| **Subdomain** | `blog.example.com` or `go.example.com` on another system | Google says it has no inherent ranking preference between subdomains and subfolders; in practice a subdomain needs its own internal links and sitemap, and links between the two matter more | Campaign landing pages, paid-traffic pages you don't want indexed, or when a proxy isn't worth the setup |
+| **Separate domain** | A new domain for the section | Starts from zero | Rarely, for a genuinely separate brand |
+
+**Reverse-proxy checklist:**
+- The proxied pages return the main domain in their canonical tags, sitemap, and Open Graph URLs, not the origin's.
+- Asset paths (CSS, JS, images, fonts) are routed too, or the pages break.
+- The origin (for example `origin.example.com`) isn't indexed separately: protect it by hostname (a password, an IP allowlist, or an `X-Robots-Tag: noindex` header set only on the origin hostname). Then confirm the proxied production responses carry no `noindex` in their HTML or headers, because an origin-wide `noindex` can pass straight through the proxy and deindex production. A `robots.txt` block alone doesn't prevent indexing.
+- Analytics and consent run on both systems, configured for one domain.
+- Test on a staging subdomain before switching production routing.
+
+Some hosted platforms provide the router themselves. Ploy ◆, for example, routes by path prefix in front of your domain (up to 20 rules), so its pages can serve on a subpath while everything else proxies to your existing origin. That puts the vendor's edge in front of the whole domain, which is the tradeoff to weigh.
+
+## Migrating Without Losing Traffic
+
+A platform migration is an SEO event. Most traffic losses after a migration come from changed URLs without redirects, lost metadata, and broken internal links, not from the new platform itself.
+
+**Before:**
+1. **Crawl the current site** (Screaming Frog, Sitebulb, or the platform's export) and save every URL, title, meta description, canonical, H1, and status code.
+2. **Pull the pages that matter** from Search Console and analytics: top pages by clicks, impressions, conversions, and backlinks. These get the most care.
+3. **Keep URLs where you can.** The safest migration changes the platform and nothing else. If URLs must change, map every old URL to its new one.
+4. **Check what the import carries.** Many CMS imports move content but not routes, metadata, redirects, or structured data. Plan to rebuild what's missing.
+5. **Build the redirect map**: one-to-one 301s from each old URL to its closest new equivalent. Never redirect everything to the homepage.
+
+**At launch:**
+- Deploy redirects at the same moment as the switch.
+- Submit the new sitemap and keep the old one available briefly so search engines see the redirects.
+- Spot-check the top pages: content, title, meta, canonical, schema, and that they return 200.
+- Confirm analytics, conversion tracking, and forms work (see the `stacks-marketing-launch` skill's site launch QA).
+
+**After:**
+- Watch Search Console for 404s and coverage drops daily for two weeks, then weekly. Fix missing redirects as they appear.
+- Compare traffic to the same period before, by page. A dip of a few weeks can be normal; a sustained drop on specific pages usually means a missing redirect or lost content.
+- Update internal links to the new URLs instead of relying on redirects.