claude-code-arcane 1.0.0

package/skills/site-architecture/references/internal-linking-playbook.md

@@ -0,0 +1,216 @@
+# Internal Linking Playbook
+
+Patterns for building an internal link structure that distributes equity intelligently and reinforces topical authority.
+
+---
+
+## The Three Goals of Internal Linking
+
+1. **Crawlability** — every page should be reachable from the homepage in 3 clicks or fewer
+2. **Equity flow** — link equity flows from authoritative pages to pages you want to rank
+3. **Topical signals** — anchor text and link context tell Google what a page is about
+
+Most sites get none of these right. The ones that do compound their SEO advantage over time.
+
+---
+
+## Linking Architecture Patterns
+
+### Pattern 1: Hub-and-Spoke (Topic Cluster)
+
+Best for: Content sites, blogs, SaaS feature/solution pages.
+
+```
+Hub (Pillar) Page
+├── Spoke 1 (Sub-topic)
+│   └── Deep 1a (Specific guide within sub-topic)
+│   └── Deep 1b
+├── Spoke 2 (Sub-topic)
+│   └── Deep 2a
+└── Spoke 3 (Sub-topic)
+```
+
+**Link rules:**
+- Hub → all spokes (contextual, in-body links)
+- Each spoke → hub (with anchor text matching hub's target keyword)
+- Each spoke → adjacent spokes (only when genuinely relevant)
+- Deep pages → parent spoke + hub
+
+**What makes this work:** The hub becomes the authority page because it receives links from everything in the cluster. Google sees a well-linked hub as the definitive resource on the topic.
+
+---
+
+### Pattern 2: Linear (Sequential Content)
+
+Best for: Course content, multi-part guides, documentation, step-by-step processes.
+
+```
+Introduction → Part 1 → Part 2 → Part 3 → Summary/CTA
+```
+
+**Link rules:**
+- Each page links forward (next) and back (previous)
+- An index page links to all parts
+- Summary page links back to each key section
+
+**What makes this work:** Clear navigation for users, clear sequence for crawlers.
+
+---
+
+### Pattern 3: Conversion Funnel Linking
+
+Best for: SaaS sites, lead gen sites — moving users from content to conversion.
+
+```
+Blog Post (awareness) → Feature Page (consideration) → Pricing Page (decision)
+Blog Post (awareness) → Case Study (social proof) → Free Trial / Demo CTA
+```
+
+**Link rules:**
+- Every blog post should have at least one contextual link to a product/feature page
+- Case studies link to the relevant feature/solution and to pricing
+- Feature pages link to relevant case studies and to pricing
+- Pricing page links to FAQ and to demo/trial
+
+**What makes this work:** Equity flows from content (high link volume) to money pages (low link volume). Most SaaS sites have this backwards — money pages get links from the nav only.
+
+---
+
+### Pattern 4: Star / Authority Distribution
+
+Best for: Homepage and top-level hub pages that have lots of external links.
+
+```
+Homepage (authority source)
+├── Service Page A (direct link from homepage)
+├── Feature Page B (direct link from homepage)
+├── Blog Category Hub (direct link from homepage)
+└── Case Studies Hub (direct link from homepage)
+```
+
+**Link rules:**
+- Homepage links only to the most important pages
+- Not to every blog post — to the category hubs
+- Each hub then distributes equity downward
+
+**What makes this work:** Homepage equity isn't diluted across 200 blog links. It concentrates on 5-8 priority pages, which then funnel it to their children.
+
+---
+
+## Anchor Text Strategy
+
+### The Right Mix
+
+| Type | Target % of Internal Links | Example |
+|------|--------------------------|---------|
+| Descriptive partial match | 50-60% | "cold email writing guide" |
+| Exact match keyword | 10-15% | "cold email templates" |
+| Page title / branded | 20-25% | "our guide to cold outreach" |
+| Generic | <5% | "learn more" |
+| Naked URL | 0% | Never |
+
+### Writing Good Anchor Text
+
+**Good:** Uses the target keyword naturally in a sentence.
+> "For tactical patterns, see our [cold email frameworks](link)."
+
+**Bad:** Forces exact match where it sounds unnatural.
+> "Click here to read our cold email templates cold email cold outreach guide."
+
+**Bad:** Generic — signals nothing.
+> "For more information, [click here](link)."
+
+### Anchor Text Diversification
+
+Don't link to the same page with the same anchor every time. Vary it. If you have 15 internal links to your "cold email templates" page:
+- 8 using variations: "email outreach templates," "cold outreach scripts," "first-email frameworks"
+- 4 using exact: "cold email templates"
+- 3 using title/branded: "our template library"
+
+This looks natural and covers a wider keyword base.
+
+---
+
+## Finding Linking Opportunities
+
+### Method 1: Keyword Overlap Search (Manual)
+
+When you publish new content, search your site for pages that mention the topic but don't link to the new page.
+
+```
+site:yourdomain.com "cold email"
+```
+
+Any page that mentions "cold email" and doesn't already link to your cold email guide is a candidate for adding a contextual link.
+
+### Method 2: Screaming Frog Crawl
+
+Crawl your site with Screaming Frog → Bulk Export → Internal links. Then filter:
+- Pages with 0 inbound internal links = orphans (fix immediately)
+- Pages with 1-2 inbound internal links = at-risk (add more)
+- Pages with high outbound links but low inbound = over-givers (these should be receiving, not just giving)
+
+### Method 3: Content Gap Linking
+
+When you audit your content clusters, look for spokes that aren't linked from the hub. The hub should explicitly link to every key spoke page. If it doesn't, the cluster is broken.
+
+---
+
+## Orphan Page Recovery
+
+An orphan page has no internal links pointing to it. It's effectively invisible to Google's link graph.
+
+**Step 1: Find your orphans**
+- Run `scripts/sitemap_analyzer.py` to get all indexed URLs
+- Cross-reference with your internal link graph (from Screaming Frog or GSC)
+- Pages in sitemap but not in internal link graph = candidates
+
+**Step 2: Classify them**
+
+| Type | Action |
+|------|--------|
+| Valuable content, no home | Find existing relevant pages to add contextual links from; add to relevant hub |
+| Landing pages (PPC, events) | These are intentionally unlinked — check if they're accidentally indexed |
+| Duplicate / thin content | Consolidate with canonical or noindex |
+| Old content no longer relevant | Consider 301 redirect to updated version or 410 |
+
+**Step 3: Fix in priority order**
+1. Orphans with inbound external links first (equity is flowing in but going nowhere)
+2. Orphans with good content and search potential
+3. Orphans with thin content (fix content first, then link)
+
+---
+
+## Internal Link Audit Checklist
+
+Run this quarterly:
+
+- [ ] Every key page is reachable in ≤3 clicks from homepage
+- [ ] Pillar/hub pages have links from all their spokes
+- [ ] All spoke pages link back to their hub
+- [ ] No orphan pages (pages with zero internal inbound links)
+- [ ] Homepage links to 5-8 priority sections only
+- [ ] Footer links limited to high-value pages (10-15 max)
+- [ ] New content published in the last 30 days has at least 3 contextual inbound internal links
+- [ ] No broken internal links (404s from internal sources)
+- [ ] Anchor text is descriptive, not generic
+- [ ] Pages with highest external backlinks are linking to money/conversion pages
+
+---
+
+## Common Patterns That Fail
+
+### The Footer Dump
+Putting 80 links in the footer because "they should be accessible." Google gives footer links minimal weight and won't thank you for linking to every blog post from there. Footer = navigation to key sections + legal. That's it.
+
+### The "Related Posts" Widget Approach Only
+Auto-generated related posts widgets are fine as supplemental linking, but they don't replace intentional contextual linking. The widget links to "related" content by tag or category — not necessarily to what you actually want to rank. Do the manual work.
+
+### The Nav-Only Money Pages
+Feature pages and pricing pages that only appear in the navigation get equity from nav links only. Powerful nav links are sitewide — but adding 5-10 contextual blog links to your pricing page is a significant equity boost. Write one blog post that organically links to pricing. That's real.
+
+### Linking to Pages You Want to Rank for the Wrong Topic
+If your /blog/seo-guide has 30 internal links to it but all the anchor text says "our guide" and "learn more," you're not sending a topical signal. The link equity flows in, but Google doesn't know what topic to attribute. Fix anchor text.
+
+### Never Touching Old Posts
+Old blog posts accumulate internal links over time because new posts link to them. But they rarely link out to newer, better content. When you publish new content, go back and update old posts to add contextual links to the new piece. This is one of the highest-ROI activities in content SEO.

package/skills/site-architecture/references/navigation-design.md

@@ -0,0 +1,32 @@
+# Navigation Design
+
+Navigation serves two masters: user experience and link equity flow. Most sites optimize for neither.
+
+## Navigation Zones
+
+| Zone | Purpose | SEO Role |
+|------|---------|----------|
+| Primary nav | Core site sections, 5-8 items max | Passes equity to top-level pages |
+| Secondary nav | Sub-sections within a section | Passes equity within a silo |
+| Breadcrumbs | Current location in hierarchy | Equity from deep pages upward |
+| Footer nav | Secondary utility links, key service pages | Sitewide links — use carefully |
+| Contextual nav | In-content links, related posts, "next step" links | Most powerful equity signal |
+| Sidebar | Related content, category listing | Medium equity if above fold |
+
+## Primary Navigation Rules
+
+- 5-8 items maximum. Cognitive load increases with every item.
+- Each nav item should link to a page you want to rank.
+- Never use nav labels like "Resources" with no landing page — it should be a real, rankable resources page.
+- Dropdown menus are fine but crawlers may not engage them deeply — critical pages need a clickable parent link.
+
+## Breadcrumbs
+
+Add breadcrumbs to every non-homepage page. They do three things:
+1. Show users where they are
+2. Create site-wide upward internal links to category/hub pages
+3. Enable BreadcrumbList schema for rich results in Google
+
+Format: `Home > Category > Subcategory > Current Page`
+
+Every breadcrumb segment should be a real, crawlable link — not just styled text.

package/skills/site-architecture/references/silo-and-linking-guide.md

@@ -0,0 +1,80 @@
+# Silo Structure, Topical Authority & Internal Linking
+
+## Silo Structure & Topical Authority
+
+A silo is a self-contained cluster of content about one topic, where all pages link to each other and to a central hub page. Google uses this to determine topical authority.
+
+### Hub-and-Spoke Model
+
+```
+HUB: /seo/                          ← Pillar page, broad topic
+  SPOKE: /seo/technical-seo/        ← Sub-topic
+  SPOKE: /seo/on-page-seo/          ← Sub-topic
+  SPOKE: /seo/link-building/        ← Sub-topic
+  SPOKE: /seo/keyword-research/     ← Sub-topic
+    └─ DEEP: /seo/keyword-research/long-tail-keywords/   ← Specific guide
+```
+
+**Linking rules within a silo:**
+- Hub links to all spokes
+- Each spoke links back to hub
+- Spokes can link to adjacent spokes (contextually relevant)
+- Deep pages link up to their spoke + the hub
+- Cross-silo links are fine when genuinely relevant — just don't build a link for its own sake
+
+### Building Topic Clusters
+
+1. Identify your core topics (usually 3-7 for a focused site)
+2. For each topic: one pillar page (the hub) that covers it broadly
+3. Create spoke content for each major sub-question within the topic
+4. Every spoke links to the pillar with relevant anchor text
+5. The pillar links down to all spokes
+6. Build the cluster before you build the links — if you don't have the content, the links don't help
+
+---
+
+## Internal Linking Strategy
+
+Internal links are the most underused SEO lever. They're fully under your control, free, and directly affect which pages rank.
+
+### Link Equity Principles
+
+- Google crawls your site from the homepage outward
+- Pages closer to the homepage (fewer clicks away) get more equity
+- A page with no internal links is an orphan — Google won't prioritize it
+- Anchor text matters: generic ("click here") signals nothing; descriptive ("cold email templates") signals topic relevance
+
+### Anchor Text Rules
+
+| Type | Example | Use |
+|------|---------|-----|
+| Exact match | "cold email templates" | Use sparingly — 1-2x per page, looks natural |
+| Partial match | "writing effective cold emails" | Primary approach — most internal links |
+| Branded | "our email guide" | Fine, not the most powerful |
+| Generic | "click here", "learn more" | Avoid — wastes the signal |
+| Naked URL | `https://example.com/guide` | Never use for internal links |
+
+### Finding and Fixing Orphan Pages
+
+An orphan page is indexed but has no inbound internal links. It's invisible to the site's link graph.
+
+How to find them:
+1. Export all indexed URLs (from GSC, Screaming Frog, or `sitemap_analyzer.py`)
+2. Export all internal links on the site
+3. Pages that appear in set A but not set B are orphans
+4. Or: run `scripts/sitemap_analyzer.py` which flags potential orphan candidates
+
+How to fix them:
+- Add contextual links from relevant existing pages
+- Add them to relevant hub pages
+- If they truly have no home, consider whether they should exist at all
+
+### The Linking Priority Stack
+
+Not all internal links are equal. From most to least powerful:
+
+1. **In-content links** — within the body copy of a relevant page. Most natural, most powerful.
+2. **Hub page links** — the pillar page linking to all its spokes. High equity because pillar pages are linked from everywhere.
+3. **Navigation links** — sitewide, consistent, but diluted by their ubiquity.
+4. **Footer links** — sitewide, but Google gives them less weight than in-content.
+5. **Sidebar links** — OK but often not in the main content flow.

package/skills/site-architecture/references/url-design-guide.md

@@ -0,0 +1,220 @@
+# URL Design Guide
+
+URL structure by site type — with examples of what good and bad looks like in practice.
+
+---
+
+## Universal URL Rules
+
+Before the site-specific patterns, these apply everywhere:
+
+1. **Lowercase always** — `/Blog/SEO-Tips` and `/blog/seo-tips` are different URLs. Always lowercase.
+2. **Hyphens, not underscores** — Google treats hyphens as word separators. Underscores join words. `/seo-tips` not `/seo_tips`.
+3. **No special characters** — No `%`, `&`, `#`, `?` in the path itself.
+4. **No trailing slash inconsistency** — Pick a convention (`/page` or `/page/`) and enforce it sitewide with redirects.
+5. **No dates in URLs unless required** — `/blog/2024/03/seo-tips` ages poorly. `/blog/seo-tips` is evergreen.
+6. **Stop words are usually fine** — `/how-to-write-cold-emails` is readable and fine. Don't obsessively remove "how", "to", "a", "the" unless the URL is very long.
+7. **Keep them short** — Under 75 characters is a good target. Shorter is usually better.
+
+---
+
+## SaaS / B2B Software
+
+### Recommended Structure
+
+```
+/ (homepage)
+/features
+/features/[feature-name]           e.g. /features/email-automation
+/pricing
+/solutions/[use-case]              e.g. /solutions/sales-teams
+/solutions/[industry]              e.g. /solutions/healthcare
+/integrations
+/integrations/[tool-name]          e.g. /integrations/salesforce
+/blog
+/blog/[post-slug]                  e.g. /blog/cold-email-templates
+/customers
+/customers/[customer-name]         e.g. /customers/acme-corp
+/about
+/changelog
+/docs                              (or subdomain: docs.example.com)
+/docs/[topic]/[subtopic]
+```
+
+### What Works and What Doesn't
+
+| ✅ Do | ❌ Don't |
+|-------|----------|
+| `/pricing` | `/pricing-plans` (redundant) |
+| `/features/email-automation` | `/product/features/email-automation/detail` (too deep) |
+| `/blog/cold-email-guide` | `/blog/articles/cold-email/complete-guide-to-cold-email` (too long) |
+| `/solutions/sales-teams` | `/solutions-for-sales-teams` (ugly) |
+| `/integrations/hubspot` | `/connect-with/hubspot-integration` |
+
+### SaaS-Specific Notes
+
+- `/features/` pages should actually be rankable landing pages, not just nav items.
+- `/solutions/` by use case captures bottom-funnel searches ("sales team email tool").
+- `/integrations/[tool]` pages are high-intent SEO goldmines — build a real page for each.
+- Blog posts should live at `/blog/[slug]` — not `/resources/`, not `/learn/`, not `/content/`. Pick one.
+- Changelog belongs at `/changelog` — some companies put it at `/releases` or `/updates`. Fine, just pick one.
+
+---
+
+## Blog / Content Site
+
+### Recommended Structure
+
+```
+/ (homepage)
+/[category]                        e.g. /seo, /email-marketing, /content
+/[category]/[post-slug]            e.g. /seo/technical-seo-audit-checklist
+/guides                            (optional hub for long-form guides)
+/guides/[guide-slug]               e.g. /guides/cold-email-complete-guide
+/tools                             (optional if you have free tools)
+/tools/[tool-name]
+/author/[author-slug]
+/tag/[tag-name]                    (often better to noindex tags)
+```
+
+### What Works and What Doesn't
+
+| ✅ Do | ❌ Don't |
+|-------|----------|
+| `/seo/keyword-research-guide` | `/seo/keyword-research/a-complete-guide-to-keyword-research-for-beginners-in-2024` |
+| `/guides/cold-email` | `/blog/2024/03/15/cold-email-guide` |
+| `/author/reza-rezvani` | `/author?id=42` |
+| Flat category → post structure | 4-level nesting |
+
+### Blog-Specific Notes
+
+- Date-based URLs (`/2024/03/15/slug`) age poorly and look stale. Avoid.
+- Tag pages create duplicate/thin content at scale. Either noindex them or give them real content.
+- If you have <500 posts, flat `/post-slug` is fine. If you have >500, category buckets help organization.
+- Author pages are worth building as real pages — they help E-E-A-T signals.
+
+---
+
+## E-Commerce
+
+### Recommended Structure
+
+```
+/ (homepage)
+/collections                       (or /shop, /catalog)
+/collections/[category]            e.g. /collections/mens-shoes
+/collections/[category]/[subcategory]   e.g. /collections/mens-shoes/running
+/products/[product-slug]           e.g. /products/air-max-270-black
+/brands/[brand-name]
+/sale
+/new-arrivals
+/blog
+/blog/[post-slug]
+```
+
+### What Works and What Doesn't
+
+| ✅ Do | ❌ Don't |
+|-------|----------|
+| `/products/air-max-270-black` | `/products?id=89472&color=black&size=10` |
+| `/collections/mens-shoes` | `/products/shoes/men/athletic/running/all-styles` |
+| Canonical on variant pages | Let `?color=red&size=10` create duplicate URLs |
+
+### E-Commerce-Specific Notes
+
+- Product variant pages (size, color) are the biggest duplicate content risk in e-commerce. Use canonical tags pointing to the base product URL, or use URL parameters and configure them in GSC.
+- Filter and sort pages (`?sort=price-asc&brand=nike`) should either be canonicalized or blocked.
+- Collection/category pages need real content to rank — not just a product grid.
+- Discontinued products: don't just delete them. 301 to closest alternative or return 410 with a helpful message.
+
+---
+
+## Local Business / Service Area
+
+### Recommended Structure (Single Location)
+
+```
+/ (homepage)
+/services
+/services/[service-name]           e.g. /services/plumbing-repair
+/about
+/contact
+/blog
+/blog/[post-slug]
+/areas-served                      (optional hub for service area pages)
+/areas-served/[city-name]          e.g. /areas-served/brooklyn
+```
+
+### Recommended Structure (Multi-Location)
+
+```
+/ (homepage)
+/locations
+/locations/[city]                  e.g. /locations/new-york
+/locations/[city]/[service]        e.g. /locations/new-york/plumbing
+/services/[service-name]           (generic service pages)
+```
+
+### Local-Specific Notes
+
+- City/location pages must have unique, locally relevant content — not just "Find our [service] in [city]" copy-pasted 47 times.
+- `/areas-served/brooklyn` should have real information about serving Brooklyn, not a thin page.
+- Multi-location sites: `/locations/[city]` works better than subdomain per city for smaller operations. Subdomains make sense for truly independent franchises.
+
+---
+
+## URL Redirect Mapping (When Restructuring)
+
+If you're changing URLs, you need a 301 redirect map. Every old URL → new URL. No exceptions.
+
+**Redirect mapping process:**
+1. Export all indexed URLs from Google Search Console (Crawl → Coverage → All)
+2. Export all inbound links to your site (use Ahrefs, Semrush, or GSC)
+3. Map old → new for every URL that has inbound links or search traffic
+4. Implement 301 redirects server-side (not JS redirects, not meta refresh)
+5. Monitor in GSC for 404 errors after migration
+6. Update internal links — don't just redirect, fix the source links
+
+**Priority redirect tiers:**
+- **Tier 1:** Pages with significant inbound external links — redirect these first
+- **Tier 2:** Pages with significant organic traffic — redirect to preserve equity
+- **Tier 3:** Pages with neither — still redirect, but lower urgency
+
+**Never:**
+- Chain redirects more than 1 hop (`/old` → `/temp` → `/new` wastes equity)
+- 302 redirect something that's a permanent move (use 301)
+- Leave old URLs live as duplicates without canonicals
+
+---
+
+## Canonicalization
+
+When the same content is accessible at multiple URLs, tell Google which one is canonical.
+
+```html
+<link rel="canonical" href="https://example.com/the-canonical-url" />
+```
+
+Common scenarios requiring canonicals:
+- `http://` vs `https://` — canonical should always be `https://`
+- `www` vs non-www — pick one, canonical + 301 the other
+- Trailing slash vs no trailing slash — `/page` and `/page/` are different URLs to Google
+- Filtered/sorted product pages — canonical to base product/collection URL
+- Paginated pages — canonical the first page (or use `rel=next`/`rel=prev`)
+- Printer-friendly versions — canonical to main page
+- Syndicated content — canonical to original source
+
+---
+
+## HTTP Status Code Reference
+
+| Code | Meaning | Use |
+|------|---------|-----|
+| 200 | OK | Normal page |
+| 301 | Moved Permanently | URL changed permanently — passes equity |
+| 302 | Found (Temporary) | Temporary redirect — does NOT pass equity |
+| 404 | Not Found | Page doesn't exist — configure a helpful 404 page |
+| 410 | Gone | Page intentionally removed — Google deindexes faster than 404 |
+| 503 | Service Unavailable | Maintenance mode — tell Google to come back later |
+
+Use 301, not 302, for all permanent URL changes.