# [THEME NAME] — Complete Build Plan

**By:** Alorig Systems  
**For:** AI Agent (Claude Code / Opus 4.6 in VSCode)  
**Version:** 1.0  
**Date:** March 2026  
**Status:** Reference Document for Development

---

## Executive Summary

A premium WordPress theme that provides the **physical infrastructure** for SAG-optimized sites. It registers all the custom post types, custom taxonomies, meta fields, and template systems needed to display a fully structured semantic site — whether that structure is built manually or pushed from IGNY8.

The theme handles presentation, structure, and site infrastructure (performance, forms, security). The IGNY8 plugin handles intelligence, content, SEO, social, and analytics.

**Two deliverables:**
1. **Theme** — CPTs, taxonomies, templates, block patterns, landing page builder, design system, WooCommerce templates
2. **Companion Plugin (Toolkit)** — Performance/caching, forms, security, SMTP, WooCommerce enhancements

**Distribution:** Free version on WordPress.org (limited patterns + features). Premium version sold on Alorig site (full pattern library, all toolkit modules, priority support).

---

## Part 1: What This Theme Does (and Doesn't Do)

### 1.1 Theme Owns (Presentation + Structure)

| Responsibility | Details |
|---|---|
| **Custom Post Types** | Services, Portfolio/Case Studies, Landing Pages, Team Members, Testimonials, FAQs, Documentation |
| **Custom Taxonomies** | Service categories, service attributes (area, type, property type), portfolio categories, documentation categories — all SAG-compatible |
| **SAG Structural Templates** | Term landing pages, cluster hub pages, attribute archive pages — all designed to display rich content, not just post lists |
| **Landing Page Builder** | Section-based CPT with pre-designed section templates + presets |
| **Block Patterns** | 50+ patterns organized by type (heroes, features, social proof, CTAs, etc.) |
| **FSE Templates** | Complete template sets for 5 site types (blog, SaaS, eCommerce, corporate, portfolio) |
| **WooCommerce Templates** | Custom shop, product, cart, checkout templates that respect SAG structure |
| **Design System** | theme.json tokens, custom utility CSS, typography, spacing scale |
| **Interlinking Display** | Renders related content sections, cluster navigation, term relationships — reading data from IGNY8 plugin or manual configuration |
| **WordPress Cleanup** | Remove bloat, conditional asset loading, zero jQuery on frontend |

### 1.2 IGNY8 Plugin Owns (Intelligence + Marketing)

The theme does NOT include any of these — they live in the IGNY8 plugin:

- SEO meta tags, title tags, canonical, robots
- Schema / JSON-LD structured data
- XML sitemaps
- Redirects + 404 monitoring
- OG tags + social meta
- Share buttons + social posting
- Analytics (GA, GTM, pixels)
- Google Search Console integration
- Content analysis + scoring
- Internal link calculation + suggestions
- Site intelligence / audit
- Content sync from IGNY8 platform
- SAG blueprint sync + taxonomy creation logic

### 1.3 Toolkit Plugin Owns (Site Infrastructure)

- Page caching + HTML optimization
- CSS/JS minification + combination
- Image optimization + WebP conversion
- Critical CSS generation
- Contact forms + submission handling
- Security hardening + firewall
- SMTP mail handling
- WooCommerce enhancements (quick view, wishlist, ajax cart, filters)

### 1.4 How They Work Together

```
┌─────────────────────────────────────────────────────────────────┐
│                         THEME                                    │
│  Registers CPTs + Taxonomies + Templates + Design System         │
│  Displays everything: pages, terms, clusters, products,          │
│  services, landing pages, interlinking sections                  │
│                                                                  │
│  Reads from:                                                     │
│  ├── IGNY8 Plugin (SEO data, related links, cluster nav,         │
│  │   term content, breadcrumbs, share buttons)                   │
│  ├── Toolkit Plugin (cached pages, form shortcodes)              │
│  └── WordPress core (menus, widgets, customizer)                 │
│                                                                  │
│  Works WITHOUT either plugin (graceful degradation)              │
└─────────────────────────────────────────────────────────────────┘

┌──────────────────────────┐  ┌──────────────────────────────────┐
│     IGNY8 PLUGIN         │  │     TOOLKIT PLUGIN               │
│  SEO, Schema, Social,    │  │  Performance, Forms,             │
│  Analytics, GSC, Linking, │  │  Security, SMTP,                │
│  Content Sync, SAG       │  │  WooCommerce Enhancements        │
│  Intelligence            │  │                                  │
│                          │  │                                  │
│  Works with ANY theme    │  │  Works with ANY theme            │
│  Enhanced with companion │  │  Enhanced with companion         │
└──────────────────────────┘  └──────────────────────────────────┘
```

**Graceful degradation:** Theme checks `function_exists('igny8')` before reading plugin data. If IGNY8 plugin is not installed, interlinking sections don't render, breadcrumbs fall back to theme's own simple breadcrumbs, term pages show WordPress default content. Everything still works — just without the intelligence layer.

---

## Part 2: SAG Structural Support

This is the core differentiator. The theme physically implements the structures that SAG requires in WordPress.

### 2.1 Custom Post Types

| CPT | Slug | Purpose | SAG Role |
|---|---|---|---|
| **Services** | `service` | Individual service pages | Maps to SAG service clusters. Each service belongs to service categories + service attributes. |
| **Landing Pages** | `landing_page` | Section-based marketing pages | Cluster hub pages, campaign pages, any freeform landing page |
| **Portfolio** | `portfolio` | Case studies, projects | Supports attribute-based filtering (industry, service type, etc.) |
| **Team Members** | `team_member` | Staff/team profiles | Used in team sections and about pages |
| **Testimonials** | `testimonial` | Client testimonials | Used in social proof sections across site |
| **FAQs** | `faq` | Frequently asked questions | Maps to clusters/terms, generates FAQPage schema (via IGNY8 plugin) |
| **Documentation** | `documentation` | Knowledge base / docs | SaaS sites: organized by doc categories |

**CPT Registration Details:**

```
service
  - Public: true
  - Has archive: true (services listing page)
  - Supports: title, editor, thumbnail, excerpt, revisions, page-attributes
  - Menu icon: dashicons-admin-tools
  - Rewrite: /services/%service_category%/%postname%/
  - Taxonomies: service_category, service_area, service_attribute, cluster

landing_page
  - Public: true
  - Has archive: false
  - Supports: title, thumbnail, excerpt, revisions
  - Does NOT support: editor (replaced by section meta box)
  - Menu icon: dashicons-layout
  - Rewrite: /l/%postname%/ (short URLs for campaigns) or /%postname%/ (flexible)

portfolio
  - Public: true
  - Has archive: true
  - Supports: title, editor, thumbnail, excerpt, revisions
  - Menu icon: dashicons-portfolio
  - Rewrite: /portfolio/%portfolio_category%/%postname%/
  - Taxonomies: portfolio_category, portfolio_tag, service_category (shared)

team_member
  - Public: true
  - Has archive: true (team page)
  - Supports: title, editor, thumbnail
  - Menu icon: dashicons-groups
  - Rewrite: /team/%postname%/

testimonial
  - Public: false (displayed via blocks/shortcodes, not individual pages)
  - Supports: title, editor, thumbnail
  - Menu icon: dashicons-format-quote

faq
  - Public: true
  - Has archive: true (FAQ page)
  - Supports: title, editor
  - Menu icon: dashicons-editor-help
  - Taxonomies: faq_category, cluster
  - Rewrite: /faq/%faq_category%/%postname%/

documentation
  - Public: true
  - Has archive: true
  - Supports: title, editor, thumbnail, page-attributes (for ordering)
  - Hierarchical: true (parent/child docs)
  - Menu icon: dashicons-book
  - Rewrite: /docs/%doc_category%/%postname%/
  - Taxonomies: doc_category
```

### 2.2 Custom Taxonomies

These taxonomies directly map to SAG dimensional axes. When IGNY8 plugin is connected, it populates these taxonomies with SAG attribute values. When used standalone, users create terms manually.

| Taxonomy | Slug | For CPTs | Hierarchical | SAG Mapping |
|---|---|---|---|---|
| **Service Category** | `service_category` | service, portfolio | Yes | Primary attribute (e.g., "Service Type": Emergency, Drain Cleaning, etc.) |
| **Service Area** | `service_area` | service | Yes | Tertiary attribute (geographic: user-populated per location) |
| **Service Attribute** | `service_attribute` | service | No | Secondary attributes (e.g., "Property Type": Residential, Commercial; "Urgency": Emergency, Same-Day) |
| **Portfolio Category** | `portfolio_category` | portfolio | Yes | Groups projects by type |
| **Portfolio Tag** | `portfolio_tag` | portfolio | No | Descriptive tags for filtering |
| **FAQ Category** | `faq_category` | faq | Yes | Groups FAQs by topic (maps to clusters) |
| **Doc Category** | `doc_category` | documentation | Yes | Documentation sections |
| **Content Cluster** | `cluster` | post, service, faq, page | No | SAG cluster assignment. Each post/service/FAQ maps to a cluster. This is the key taxonomy that ties content to the SAG grid. |
| **Topic Tag** | `topic_tag` | post, service, faq, documentation | No | Granular topical tags beyond clusters |

**WooCommerce Taxonomies (when Woo is active):**

The theme does NOT register WooCommerce's built-in taxonomies (product_cat, product_tag, pa_*). Instead it:
- Respects and templates all WooCommerce taxonomies natively
- Provides rich term archive templates for product_cat, product_tag
- Provides attribute archive templates for all pa_* taxonomies
- Registers the `cluster` taxonomy for the `product` post type too — so products can be cluster-mapped

### 2.3 Meta Fields Per CPT

**Service Meta Fields:**

```
_theme_service_price_range        -- Text: e.g., "$150 - $500"
_theme_service_duration           -- Text: e.g., "2-4 hours"
_theme_service_process_steps      -- JSON array: [{step_number, title, description, icon}]
_theme_service_outcomes           -- JSON array: [{title, description}]
_theme_service_faqs               -- JSON array: [{question, answer}] (also rendered as FAQPage schema via IGNY8)
_theme_service_cta_text           -- Text: custom CTA button text
_theme_service_cta_url            -- URL: custom CTA destination
_theme_service_areas_served       -- JSON array: geographic areas (populates service_area terms)
_theme_service_gallery            -- JSON array: attachment IDs
_theme_service_related_services   -- JSON array: post IDs (manual override; IGNY8 auto-calculates if connected)
```

**Portfolio Meta Fields:**

```
_theme_portfolio_client           -- Text: client name
_theme_portfolio_date             -- Date: project completion date
_theme_portfolio_url              -- URL: live project link
_theme_portfolio_results          -- JSON array: [{metric, value, description}] e.g., "50% increase in traffic"
_theme_portfolio_technologies     -- Text: comma-separated tech/tools used
_theme_portfolio_testimonial_id   -- Int: linked testimonial post ID
_theme_portfolio_gallery          -- JSON array: attachment IDs
_theme_portfolio_before_after     -- JSON: {before_image, after_image}
```

**Team Member Meta Fields:**

```
_theme_team_position              -- Text: job title
_theme_team_email                 -- Email
_theme_team_phone                 -- Text
_theme_team_social                -- JSON: {linkedin, twitter, facebook, website}
_theme_team_order                 -- Int: display order
_theme_team_department            -- Text: department/group
```

**Testimonial Meta Fields:**

```
_theme_testimonial_author_name    -- Text: person's name
_theme_testimonial_author_title   -- Text: job title
_theme_testimonial_company        -- Text: company name
_theme_testimonial_rating         -- Int: 1-5 stars
_theme_testimonial_image          -- Attachment ID: author photo
_theme_testimonial_featured       -- Boolean: show in featured sections
_theme_testimonial_service_id     -- Int: linked service post ID
_theme_testimonial_product_id     -- Int: linked product ID (WooCommerce)
```

**FAQ Meta Fields:**

```
(FAQs use title = question, editor = answer. Additional meta:)
_theme_faq_order                  -- Int: display order within category
_theme_faq_schema_enabled         -- Boolean: include in FAQPage schema
```

**Documentation Meta Fields:**

```
_theme_doc_sidebar_enabled        -- Boolean: show doc sidebar navigation
_theme_doc_toc_enabled            -- Boolean: show table of contents
_theme_doc_last_reviewed          -- Date: content last reviewed date
_theme_doc_related_docs           -- JSON array: related doc post IDs
```

### 2.4 Term Landing Page Templates

Every taxonomy term archive in this theme renders as a **rich landing page**, not a simple post list. This is the SAG architecture in action.

**Template hierarchy for term archives:**

```
taxonomy-service_category-{slug}.html    → Specific service category
taxonomy-service_category.html           → All service categories
taxonomy-service_area.html               → Service area archives
taxonomy-service_attribute.html          → Service attribute archives
taxonomy-cluster.html                    → Cluster hub pages
taxonomy-faq_category.html               → FAQ category pages
taxonomy-product_cat.html                → WooCommerce product categories
taxonomy-product_tag.html                → WooCommerce product tags
taxonomy-pa_{attribute}.html             → WooCommerce product attributes
archive-service.html                     → Services listing
archive-portfolio.html                   → Portfolio listing
archive-faq.html                         → FAQ listing
archive-documentation.html               → Docs listing
```

**Term Landing Page Structure (universal):**

Every term archive template follows this section order:

```
1. TERM HERO
   - Term name as H1
   - Term description (rich content from _igny8_term_content if IGNY8 active,
     otherwise standard WordPress term description)
   - Breadcrumbs
   - Post count

2. KEY SUBTOPICS (if child terms exist)
   - Grid of child term cards
   - Each card: term name, description excerpt, post count, link
   - This creates the dimensional navigation (e.g., "Emergency Plumbing" term
     page shows child terms like "Burst Pipe Emergency", "Frozen Pipe Emergency")

3. CONTENT GRID
   - Posts/services/products belonging to this term
   - Configurable layout: grid (2/3/4 col), list
   - Filterable by secondary taxonomy if applicable
   - Pagination

4. RELATED TERMS (sibling terms in same taxonomy)
   - "Related [Taxonomy Label]" section
   - If IGNY8 active: reads _igny8_term_related_terms for intelligent suggestions
   - If standalone: shows sibling terms (same parent)

5. CLUSTER CROSS-LINKS (if IGNY8 active)
   - "Related Topics" section
   - Links to other clusters that share dimensional axes
   - E.g., "Dog x Joint Health" cluster page links to "Dog x Senior Care" and "Cat x Joint Health"

6. FAQ SECTION (if term has FAQs)
   - If IGNY8 active: reads _igny8_term_faq
   - If standalone: shows FAQ posts in matching faq_category
   - Accordion display

7. CTA / CONVERSION
   - Configurable per term or global default
   - "Get a free quote", "Browse products", "Contact us" etc.
```

**Cluster Hub Page Template (taxonomy-cluster.html):**

Cluster pages are special — they're the hub of a SAG cluster. The template:

```
1. CLUSTER HERO
   - Cluster name as H1
   - Cluster description (rich content)
   - Breadcrumbs showing dimensional path
   - Total content count in cluster

2. HUB CONTENT
   - The main cluster hub article content
   - This is the comprehensive "pillar" page for the cluster
   - Content from _igny8_term_content or editor

3. SUPPORTING CONTENT
   - All posts/services/products mapped to this cluster
   - Organized by content type: posts first, then services, then products
   - Each with excerpt, featured image, link

4. ATTRIBUTE NAVIGATION
   - "Browse by [Attribute]" sections
   - Shows which attribute values this cluster intersects
   - E.g., for "Dog Anxiety Relief Products" cluster:
     "Pet Type: Dog" | "Pet Need: Anxiety Relief" | "Product Category: Health"

5. RELATED CLUSTERS
   - Other clusters sharing one or more attribute values
   - Intelligent cross-linking that builds the SAG web

6. FAQ
   - Cluster-specific FAQs

7. CTA
```

### 2.5 Interlinking Display Components

The theme provides template parts that render interlinking sections. These read data from IGNY8 plugin when available, or from manual post meta when not.

**Component: Related Content Block**

```
Location: After post/service/product content
Data source: _igny8_related_links post meta (array of {post_id, anchor_text, priority})
Fallback: WordPress related posts by shared categories/tags
Display: 3-4 cards with featured image, title, excerpt
Template part: parts/related-content.html
```

**Component: Cluster Navigation**

```
Location: Sidebar or after content
Data source: IGNY8 plugin API → igny8()->linking->get_cluster_navigation($post_id)
Fallback: Posts in same cluster taxonomy term
Display: "More in [Cluster Name]" with linked list
Template part: parts/cluster-navigation.html
```

**Component: Attribute Browse**

```
Location: Term archive pages, sidebar
Data source: Custom taxonomy terms for current context
Display: Pills/tags showing browsable attribute values
Template part: parts/attribute-browse.html
E.g., on a service page: "Service Type: Emergency" | "Property: Residential" | "Area: Downtown"
```

**Component: Breadcrumb Trail**

```
Location: Below header on all pages
Data source: IGNY8 plugin breadcrumbs (if active), else theme's own breadcrumbs
Display: Home > [Taxonomy] > [Parent Term] > [Child Term] > [Post Title]
Template part: parts/breadcrumbs.html
SAG aware: Breadcrumbs follow dimensional path, not just hierarchy
```

**Component: Term Quick Links**

```
Location: Single post/service sidebar or footer
Data source: All terms assigned to current post across all taxonomies
Display: Grouped by taxonomy label: "Service Type: Emergency | Drain Cleaning"
                                     "Property Type: Residential"
                                     "Cluster: Emergency Drain Services"
Template part: parts/term-quick-links.html
```

**Component: Child Term Grid**

```
Location: Term archive pages (when term has children)
Data source: get_term_children() + term meta
Display: Card grid with term image, name, description, post count
Template part: parts/child-term-grid.html
```

---

## Part 3: Landing Page System

### 3.1 Architecture

Identical to previous plan — section-based CPT with repeater meta box. No changes needed here since landing pages are theme-owned.

**CPT:** `landing_page`
**Meta key:** `_theme_landing_sections` (serialized array of section objects)

### 3.2 Section Types (15 total)

| # | Section Type | Key Fields |
|---|---|---|
| 1 | **hero** | headline, subheadline, cta_text, cta_url, cta2_text, cta2_url, background_type (color/image/gradient/video), background_value, text_alignment, overlay_opacity |
| 2 | **features-grid** | section_title, section_subtitle, columns (2/3/4), items[] (icon, title, description, link) |
| 3 | **how-it-works** | section_title, section_subtitle, steps[] (number, title, description, icon) |
| 4 | **social-proof** | section_title, layout (grid/slider/single), testimonials[] (quote, name, title, image, company, rating) |
| 5 | **pricing** | section_title, section_subtitle, billing_toggle, plans[] (name, monthly_price, annual_price, description, features[], cta_text, cta_url, is_featured, badge) |
| 6 | **faq** | section_title, section_subtitle, items[] (question, answer), schema_enabled |
| 7 | **cta-band** | headline, subheadline, cta_text, cta_url, background_color, text_color |
| 8 | **content-block** | section_title, content (wp_editor), image, image_position (left/right/top), background |
| 9 | **stats-counter** | section_title, stats[] (number, suffix, label), background, animate |
| 10 | **team** | section_title, section_subtitle, members[] (name, title, bio, image, social_links) OR pull from team_member CPT |
| 11 | **portfolio-grid** | section_title, columns, items[] (title, category, image, link, description) OR pull from portfolio CPT |
| 12 | **contact-form** | section_title, section_subtitle, form_shortcode, show_map, address, phone, email |
| 13 | **video-embed** | section_title, video_url, poster_image, autoplay, full_width |
| 14 | **logo-bar** | section_title, logos[] (image, alt, link), style (grid/scroll) |
| 15 | **comparison-table** | section_title, columns[] (heading), rows[] (label, values[]), highlight_column |

### 3.3 Landing Page Presets

| Preset | Sections in Order |
|---|---|
| **SaaS Product** | hero → logo-bar → features-grid → how-it-works → social-proof → pricing → faq → cta-band |
| **Service Business** | hero → features-grid → content-block → stats-counter → social-proof → team → contact-form → cta-band |
| **Product Launch** | hero → content-block → features-grid → video-embed → social-proof → pricing → faq → cta-band |
| **Lead Generation** | hero → features-grid → social-proof → cta-band |
| **Portfolio / Agency** | hero → portfolio-grid → how-it-works → social-proof → stats-counter → contact-form |
| **Event / Webinar** | hero → content-block → features-grid → social-proof → faq → cta-band |
| **Cluster Hub** | hero → content-block → features-grid → faq → cta-band |
| **Term Landing** | hero → content-block → features-grid → social-proof → faq → cta-band |

The last two presets are specifically for when IGNY8 generates hub/term content — the content gets pasted into the section fields for immediate designed output.

---

## Part 4: Theme File Structure

```
theme-name/
├── style.css
├── theme.json
├── functions.php
├── screenshot.png
│
├── assets/
│   ├── css/
│   │   ├── base.css                   # Reset, typography, utilities (~25KB)
│   │   ├── blocks.css                 # Block pattern styles
│   │   ├── components.css             # Shared components (cards, buttons, badges, etc.)
│   │   ├── landing-sections.css       # Landing page section styles
│   │   ├── term-pages.css             # Term archive / landing page styles
│   │   ├── woocommerce.css            # WooCommerce overrides (conditional)
│   │   └── admin.css                  # Admin-only styles
│   ├── js/
│   │   ├── app.js                     # Core frontend (~8KB)
│   │   ├── navigation.js              # Mobile menu, dropdowns
│   │   ├── scroll-effects.js          # Sticky header, smooth scroll, back-to-top
│   │   ├── counter-animation.js       # Stats counter animation (conditional)
│   │   ├── accordion.js               # FAQ accordion (conditional)
│   │   ├── landing-page-admin.js      # Section builder admin UI
│   │   └── meta-box-admin.js          # CPT meta box admin UI
│   ├── images/
│   │   └── placeholder.svg
│   └── fonts/
│       ├── inter-400.woff2
│       ├── inter-500.woff2
│       ├── inter-600.woff2
│       └── inter-700.woff2
│
├── inc/
│   ├── setup.php                      # Theme supports, menus, sidebars, image sizes
│   ├── cleanup.php                    # Remove WP bloat
│   ├── enqueue.php                    # Conditional asset loading
│   ├── template-tags.php              # Template helper functions
│   ├── breadcrumbs.php                # Fallback breadcrumbs (when IGNY8 not active)
│   ├── walkers.php                    # Custom menu walkers
│   ├── customizer.php                 # Theme customizer settings
│   ├── theme-bridge.php               # IGNY8 plugin detection + data reading
│   │
│   ├── cpt/                           # Custom Post Types
│   │   ├── register.php               # All CPT registrations
│   │   ├── service.php                # Service CPT specifics + meta boxes
│   │   ├── landing-page.php           # Landing page CPT specifics
│   │   ├── portfolio.php              # Portfolio CPT + meta boxes
│   │   ├── team-member.php            # Team member CPT + meta boxes
│   │   ├── testimonial.php            # Testimonial CPT + meta boxes
│   │   ├── faq.php                    # FAQ CPT + meta boxes
│   │   └── documentation.php          # Documentation CPT + meta boxes
│   │
│   ├── taxonomies/                    # Custom Taxonomies
│   │   ├── register.php               # All taxonomy registrations
│   │   ├── service-category.php       # Service category specifics
│   │   ├── service-area.php           # Service area specifics
│   │   ├── service-attribute.php      # Service attribute specifics
│   │   ├── cluster.php                # Content cluster taxonomy
│   │   ├── portfolio-category.php     # Portfolio category
│   │   ├── faq-category.php           # FAQ category
│   │   └── doc-category.php           # Documentation category
│   │
│   ├── meta-fields/                   # Meta box definitions
│   │   ├── class-meta-box-base.php    # Base meta box class
│   │   ├── service-meta.php           # Service meta fields
│   │   ├── portfolio-meta.php         # Portfolio meta fields
│   │   ├── team-meta.php              # Team member meta fields
│   │   ├── testimonial-meta.php       # Testimonial meta fields
│   │   ├── faq-meta.php               # FAQ meta fields
│   │   └── doc-meta.php               # Documentation meta fields
│   │
│   ├── landing-pages/                 # Landing page system
│   │   ├── register-cpt.php           # (delegated from cpt/landing-page.php)
│   │   ├── meta-boxes.php             # Section repeater meta box
│   │   ├── presets.php                # Pre-built page layouts
│   │   ├── render.php                 # Frontend section renderer
│   │   └── sections/                  # Individual section templates
│   │       ├── hero.php
│   │       ├── features-grid.php
│   │       ├── how-it-works.php
│   │       ├── social-proof.php
│   │       ├── pricing.php
│   │       ├── faq.php
│   │       ├── cta-band.php
│   │       ├── content-block.php
│   │       ├── stats-counter.php
│   │       ├── team.php
│   │       ├── portfolio-grid.php
│   │       ├── contact-form.php
│   │       ├── video-embed.php
│   │       ├── logo-bar.php
│   │       └── comparison-table.php
│   │
│   ├── interlinking/                  # Interlinking display components
│   │   ├── related-content.php        # Related content block (reads IGNY8 data)
│   │   ├── cluster-navigation.php     # "More in this cluster" block
│   │   ├── attribute-browse.php       # Attribute pills/tag navigation
│   │   ├── term-quick-links.php       # Term assignments display
│   │   └── child-term-grid.php        # Child term card grid
│   │
│   ├── blocks/                        # Custom Gutenberg blocks
│   │   ├── register.php
│   │   ├── pricing-table/
│   │   ├── feature-grid/
│   │   ├── testimonial-slider/
│   │   ├── stats-counter/
│   │   ├── team-grid/
│   │   ├── faq-accordion/
│   │   ├── cta-banner/
│   │   ├── logo-carousel/
│   │   ├── comparison-table/
│   │   ├── icon-box/
│   │   ├── service-grid/              # Pulls from service CPT
│   │   ├── portfolio-showcase/        # Pulls from portfolio CPT
│   │   └── doc-sidebar/               # Documentation navigation
│   │
│   └── patterns/                      # Block patterns
│       ├── register.php
│       ├── heroes/
│       │   ├── hero-centered.php
│       │   ├── hero-split.php
│       │   ├── hero-video-bg.php
│       │   └── hero-slider.php
│       ├── content/
│       │   ├── features-3col.php
│       │   ├── features-alternating.php
│       │   ├── how-it-works.php
│       │   └── benefits-icons.php
│       ├── social-proof/
│       │   ├── testimonials-grid.php
│       │   ├── testimonials-slider.php
│       │   ├── logo-bar.php
│       │   └── stats-row.php
│       ├── conversion/
│       │   ├── cta-simple.php
│       │   ├── cta-with-form.php
│       │   ├── pricing-section.php
│       │   └── newsletter-signup.php
│       ├── services/                  # Service-specific patterns
│       │   ├── service-cards.php
│       │   ├── service-list.php
│       │   └── service-with-sidebar.php
│       ├── portfolio/
│       │   ├── portfolio-grid.php
│       │   ├── portfolio-masonry.php
│       │   └── case-study-layout.php
│       └── footers/
│           ├── footer-4col.php
│           ├── footer-centered.php
│           └── footer-minimal.php
│
├── templates/                         # FSE templates
│   ├── index.html
│   ├── home.html
│   ├── single.html                    # Single post
│   ├── single-service.html            # Single service
│   ├── single-portfolio.html          # Single portfolio item
│   ├── single-landing_page.html       # Landing page (section renderer)
│   ├── single-documentation.html      # Single doc (with sidebar nav)
│   ├── page.html
│   ├── archive.html                   # Default archive
│   ├── archive-service.html           # Services listing
│   ├── archive-portfolio.html         # Portfolio listing
│   ├── archive-faq.html               # FAQ listing
│   ├── archive-documentation.html     # Docs home
│   ├── taxonomy-service_category.html # Service category term page
│   ├── taxonomy-service_area.html     # Service area term page
│   ├── taxonomy-service_attribute.html # Service attribute term page
│   ├── taxonomy-cluster.html          # Cluster hub page
│   ├── taxonomy-faq_category.html     # FAQ category page
│   ├── taxonomy-product_cat.html      # WooCommerce product category (rich landing)
│   ├── taxonomy-product_tag.html      # WooCommerce product tag
│   ├── search.html
│   ├── 404.html
│   │
│   ├── starter-blog/
│   │   ├── front-page.html
│   │   ├── single.html
│   │   └── archive.html
│   ├── starter-saas/
│   │   ├── front-page.html
│   │   ├── page-features.html
│   │   ├── page-pricing.html
│   │   └── page-docs.html
│   ├── starter-corporate/
│   │   ├── front-page.html
│   │   ├── page-about.html
│   │   ├── page-services.html
│   │   └── page-contact.html
│   ├── starter-ecommerce/
│   │   ├── front-page.html
│   │   ├── archive-product.html
│   │   └── single-product.html
│   └── starter-portfolio/
│       ├── front-page.html
│       ├── archive-portfolio.html
│       └── single-portfolio.html
│
├── parts/                             # FSE template parts
│   ├── header.html
│   ├── header-transparent.html
│   ├── header-minimal.html
│   ├── footer.html
│   ├── footer-minimal.html
│   ├── sidebar.html
│   ├── sidebar-docs.html              # Documentation sidebar navigation
│   ├── post-meta.html
│   ├── author-box.html
│   ├── related-content.html           # Related content (reads IGNY8 data)
│   ├── cluster-navigation.html        # Cluster siblings
│   ├── attribute-browse.html          # Attribute term pills
│   ├── term-quick-links.html          # Assigned terms display
│   ├── child-term-grid.html           # Child term cards
│   ├── breadcrumbs.html               # Breadcrumbs (IGNY8 or fallback)
│   ├── term-hero.html                 # Term archive hero section
│   ├── term-content.html              # Term rich content section
│   ├── term-faq.html                  # Term FAQ section
│   ├── comments.html
│   └── pagination.html
│
└── woocommerce/                       # WooCommerce template overrides
    ├── archive-product.php            # Shop page (SAG-structured)
    ├── single-product.php             # Product page (enhanced)
    ├── taxonomy-product_cat.php       # Product category (rich landing)
    ├── content-product.php            # Product card in archives
    ├── cart/
    ├── checkout/
    └── myaccount/
```

---

## Part 5: Toolkit Plugin (Companion)

### 5.1 Scope

Only site infrastructure — no SEO, no social, no analytics (those are in IGNY8 plugin).

| Module | Purpose | Replaces |
|---|---|---|
| **Performance** | Page cache, asset optimization, image optimization, critical CSS, HTML minification, preload/prefetch | WP Rocket, LiteSpeed Cache, Smush |
| **Forms** | Form builder, submissions, notifications, anti-spam | Contact Form 7, Gravity Forms |
| **Security** | Login protection, firewall, hardening, security headers, audit log | Wordfence, Sucuri |
| **SMTP** | Mail delivery override, email log, test email | WP Mail SMTP |
| **WooCommerce** | Quick view, wishlist, AJAX cart, product filters, enhanced gallery | 5-6 separate Woo plugins |

### 5.2 Plugin File Structure

```
theme-name-toolkit/
├── theme-name-toolkit.php
├── readme.txt
│
├── includes/
│   ├── class-toolkit.php              # Main class
│   ├── class-module-manager.php       # Module toggle system
│   │
│   ├── modules/
│   │   ├── performance/
│   │   │   ├── class-performance-module.php
│   │   │   ├── class-page-cache.php
│   │   │   ├── class-asset-optimizer.php
│   │   │   ├── class-image-optimizer.php
│   │   │   ├── class-critical-css.php
│   │   │   ├── class-html-minifier.php
│   │   │   ├── class-browser-cache.php
│   │   │   ├── class-preload.php
│   │   │   └── class-database-optimizer.php
│   │   │
│   │   ├── forms/
│   │   │   ├── class-forms-module.php
│   │   │   ├── class-form-builder.php
│   │   │   ├── class-form-renderer.php
│   │   │   ├── class-form-processor.php
│   │   │   ├── class-form-notifications.php
│   │   │   ├── class-form-entries.php
│   │   │   └── class-form-antispam.php
│   │   │
│   │   ├── security/
│   │   │   ├── class-security-module.php
│   │   │   ├── class-login-protection.php
│   │   │   ├── class-firewall.php
│   │   │   ├── class-hardening.php
│   │   │   ├── class-headers.php
│   │   │   └── class-audit-log.php
│   │   │
│   │   ├── smtp/
│   │   │   ├── class-smtp-module.php
│   │   │   ├── class-smtp-mailer.php
│   │   │   ├── class-email-log.php
│   │   │   └── class-email-test.php
│   │   │
│   │   └── woocommerce/
│   │       ├── class-woo-module.php
│   │       ├── class-quick-view.php
│   │       ├── class-wishlist.php
│   │       ├── class-ajax-cart.php
│   │       ├── class-product-filters.php
│   │       └── class-product-gallery.php
│   │
│   └── admin/
│       ├── class-dashboard.php
│       └── views/
│           └── dashboard.php
│
└── languages/
```

---

## Part 6: Design System (theme.json)

Same as previous plan — complete design token system with colors, typography, spacing, shadows, border radius, transitions. No changes needed.

Key additions specific to SAG:

```jsonc
{
  "custom": {
    // Term page specific tokens
    "termPage": {
      "heroPadding": "4rem",
      "sectionGap": "3rem",
      "childTermCardMinWidth": "250px"
    },
    // Interlinking component tokens
    "interlink": {
      "relatedBg": "var(--wp--preset--color--surface)",
      "clusterNavBorder": "var(--wp--preset--color--primary-light)",
      "attributePillBg": "var(--wp--preset--color--primary-light)",
      "attributePillText": "var(--wp--preset--color--primary-dark)"
    }
  }
}
```

---

## Part 7: Setup Wizard

Theme activation launches a wizard (works independently of plugin wizards):

### Step 1: Site Type
- Blog, SaaS, eCommerce, Corporate/Services, Portfolio
- Determines: which CPTs are active, which starter templates import, which patterns are highlighted

### Step 2: Brand Identity
- Logo upload
- Primary color (generates full palette)
- Font selection (heading + body from curated list)
- Live preview panel

### Step 3: CPT Configuration
Based on site type, shows which CPTs will be enabled:
- Services site → Services, FAQ, Testimonials, Team enabled
- SaaS site → Documentation, FAQ, Team enabled
- eCommerce → WooCommerce detected, FAQ, Testimonials enabled
- Blog → FAQ enabled, others optional
- User can toggle any CPT on/off

### Step 4: Demo Content Import
- Import starter content for selected site type
- Or start blank
- Creates: homepage, core pages, sample CPT entries, sample taxonomy terms

### Step 5: Plugin Recommendations
- "For full SEO and content intelligence, install IGNY8 plugin"
- "For performance and security, install [Theme] Toolkit"
- Download/install buttons (or WordPress.org search links)

---

## Part 8: Build Execution Plan

### Phase 1: Foundation (Days 1-3)

| Day | Task |
|---|---|
| 1 | Theme skeleton: style.css, functions.php, theme.json (full tokens), cleanup.php, enqueue.php |
| 1 | FSE base: index.html, single.html, page.html, archive.html, 404.html, search.html |
| 2 | Template parts: header.html (3 variants), footer.html (3 variants), sidebar.html, breadcrumbs.html |
| 2 | CSS design system: base.css (reset, typography, utilities), components.css (cards, buttons, badges, forms) |
| 3 | Core JS: app.js, navigation.js, scroll-effects.js |
| 3 | Theme customizer: logo, colors, fonts, layout options |

### Phase 2: CPTs + Taxonomies (Days 4-6)

| Day | Task |
|---|---|
| 4 | Register all 7 CPTs with full configuration (supports, rewrite rules, menu icons) |
| 4 | Register all custom taxonomies with hierarchical/non-hierarchical settings |
| 5 | Meta boxes: service meta, portfolio meta, team meta, testimonial meta |
| 5 | Meta boxes: FAQ meta, documentation meta |
| 6 | Admin UI: meta box JS for repeater fields (process steps, outcomes, gallery, social links) |
| 6 | Theme bridge: IGNY8 plugin detection, graceful fallback functions |

### Phase 3: Term Landing Page Templates (Days 7-9)

| Day | Task |
|---|---|
| 7 | Term hero template part: H1, description, breadcrumbs, post count |
| 7 | Term content template part: rich content from IGNY8 or WP description |
| 8 | Child term grid template part |
| 8 | Term archive templates: taxonomy-service_category, taxonomy-service_area, taxonomy-service_attribute |
| 9 | Term archive templates: taxonomy-cluster (hub page), taxonomy-faq_category |
| 9 | WooCommerce term templates: taxonomy-product_cat, taxonomy-product_tag |
| 9 | Term page CSS: term-pages.css |

### Phase 4: Interlinking Display (Days 10-11)

| Day | Task |
|---|---|
| 10 | Related content component: read IGNY8 data or fallback to category matching |
| 10 | Cluster navigation component: sidebar/footer cluster siblings |
| 11 | Attribute browse component: term pills navigation |
| 11 | Term quick links, child term grid finalization |
| 11 | Integration testing: all components with IGNY8 active and inactive |

### Phase 5: Landing Page System (Days 12-14)

| Day | Task |
|---|---|
| 12 | Landing page CPT + section repeater meta box |
| 12 | Admin JS: dynamic section fields, drag-to-reorder, add/remove/duplicate |
| 13 | Section templates (first 8): hero, features-grid, how-it-works, social-proof, pricing, faq, cta-band, content-block |
| 13 | Section CSS: landing-sections.css |
| 14 | Section templates (remaining 7): stats-counter, team, portfolio-grid, contact-form, video-embed, logo-bar, comparison-table |
| 14 | Presets: all 8 preset configurations, preset loader on page creation |
| 14 | Frontend renderer: section loop, responsive testing |

### Phase 6: Single Templates (Days 15-16)

| Day | Task |
|---|---|
| 15 | single-service.html: hero, content, process steps, outcomes, gallery, FAQs, related services, CTA |
| 15 | single-portfolio.html: hero, content, results, gallery, before/after, testimonial, related projects |
| 16 | single-documentation.html: sidebar nav, content, TOC, related docs, prev/next navigation |
| 16 | archive templates: archive-service, archive-portfolio, archive-faq, archive-documentation |

### Phase 7: Custom Blocks + Patterns (Days 17-19)

| Day | Task |
|---|---|
| 17 | Custom blocks: pricing-table, feature-grid, testimonial-slider, stats-counter, faq-accordion |
| 18 | Custom blocks: team-grid, cta-banner, logo-carousel, comparison-table, icon-box |
| 18 | Custom blocks: service-grid (CPT-powered), portfolio-showcase (CPT-powered), doc-sidebar |
| 19 | Block patterns: heroes (4), content (4), social proof (4), conversion (4), services (3), portfolio (3), footers (3) |

### Phase 8: Site-Type Starters + WooCommerce (Days 20-22)

| Day | Task |
|---|---|
| 20 | Starter templates: blog (homepage, single, archive) |
| 20 | Starter templates: SaaS (homepage, features, pricing, docs) |
| 21 | Starter templates: corporate (homepage, about, services, contact) |
| 21 | Starter templates: eCommerce (homepage, shop, product) |
| 22 | Starter templates: portfolio (homepage, portfolio, case study) |
| 22 | WooCommerce template overrides: shop, product, cart, checkout, account |

### Phase 9: Toolkit Plugin (Days 23-27)

| Day | Task |
|---|---|
| 23 | Plugin skeleton: main file, module manager, dashboard |
| 23 | Performance module: page cache, HTML minifier |
| 24 | Performance module: asset optimizer, image optimizer, WebP, lazy load |
| 24 | Performance module: critical CSS, preload, browser cache |
| 25 | Forms module: builder UI, field types, renderer, processor |
| 25 | Forms module: notifications, entries admin, anti-spam |
| 26 | Security module: login protection, firewall, hardening, headers, audit log |
| 26 | SMTP module: mailer, email log, test email |
| 27 | WooCommerce module: quick view, ajax cart, wishlist, product filters |

### Phase 10: Setup Wizard + Polish (Days 28-30)

| Day | Task |
|---|---|
| 28 | Setup wizard: 5-step flow (site type → brand → CPTs → demo → plugins) |
| 28 | Demo content: sample data for each site type |
| 29 | Cross-component testing: all CPTs, taxonomies, templates, interlinking |
| 29 | Performance audit: measure load times per site type |
| 30 | Responsive testing: all templates at all breakpoints |
| 30 | Accessibility: ARIA labels, keyboard nav, contrast |
| 30 | Package: readme.txt, screenshot, build script |

---

## Part 9: Performance Targets

Same targets as previous plan:

| Metric | Target |
|---|---|
| First Contentful Paint | < 1.0s |
| Largest Contentful Paint | < 1.5s |
| Total Blocking Time | < 50ms |
| Cumulative Layout Shift | < 0.05 |
| Page Weight | < 200KB (uncached) |
| PageSpeed Score | 95+ mobile |
| Theme CSS total | < 35KB gzipped |
| Frontend JS total | < 15KB gzipped |

---

## Part 10: Naming Conventions

### PHP
- Theme prefix: `themename_` (replace with chosen name)
- Toolkit prefix: `themename_toolkit_`
- CPT slugs: `service`, `landing_page`, `portfolio`, `team_member`, `testimonial`, `faq`, `documentation`
- Taxonomy slugs: `service_category`, `service_area`, `service_attribute`, `cluster`, `portfolio_category`, `portfolio_tag`, `faq_category`, `doc_category`, `topic_tag`
- Meta key prefix: `_theme_` for theme meta, reads `_igny8_` for plugin data
- Text domain: `theme-name`

### CSS
- BEM: `.tn-block__element--modifier`
- Term page classes: `.tn-term-hero`, `.tn-term-content`, `.tn-child-grid`
- Landing section classes: `.tn-section--hero`, `.tn-section--pricing`
- Interlinking classes: `.tn-related`, `.tn-cluster-nav`, `.tn-attribute-browse`

### JavaScript
- ES6+, vanilla JS, no jQuery on frontend
- Each feature in own file, loaded conditionally

---

## Part 11: Free vs Premium Split (WordPress.org)

**Free Theme (WordPress.org):**
- All CPTs and taxonomies
- All term landing page templates
- Basic interlinking display components
- 3 landing page section types (hero, content-block, cta-band)
- 2 presets (generic, service)
- 10 block patterns (2 per category)
- 2 starter templates (blog, corporate)
- IGNY8 plugin bridge (full)
- Basic customizer options

**Premium Theme:**
- All 15 landing page section types
- All 8 presets
- All 50+ block patterns
- All 5 starter templates
- WooCommerce templates
- Setup wizard with demo import
- Priority support
- Updates for 1 year

**Free Toolkit Plugin (WordPress.org):**
- Performance: page cache + HTML minification
- Security: basic hardening + login protection
- Forms: basic form builder (5 field types)
- SMTP: basic mail override

**Premium Toolkit:**
- Performance: full suite (critical CSS, image optimization, WebP, asset optimization)
- Security: full suite (firewall, audit log, 2FA)
- Forms: full suite (conditional logic, multi-step, file upload, entries management)
- SMTP: full suite (email log, templates)
- WooCommerce: all enhancements

---

*End of Theme Build Plan*