igny8/v2/V2-Execution-Docs/03C-companion-theme.md

# IGNY8 Phase 3: Companion Theme (03C)
## FSE Block Theme Optimized for IGNY8 + SAG Architecture

**Document Version:** 1.0
**Date:** 2026-03-23
**Phase:** IGNY8 Phase 3 — WordPress Ecosystem
**Status:** Build Ready
**Source of Truth:** Codebase at `/data/app/igny8/`
**Audience:** Claude Code, WordPress Developers, Theme Developers, Architects

---

## 1. CURRENT STATE

### No Companion Theme Exists
- Users run generic themes (Astra, GeneratePress, Kadence, etc.) alongside the IGNY8 plugin
- Plugin provides data (SEO meta, schema, internal links) but cannot control template rendering
- SAG taxonomy structures (service_category, service_area, clusters) have no optimized archive templates
- Term landing pages render as basic post lists — no rich content, FAQ, or cross-linking
- Cluster hub pages have no dedicated template with navigation and content grid

### Plugin API Available (03A + 03B)
When the IGNY8 plugin is active, the theme can access:
- `igny8()->seo->get_title()`, `igny8()->seo->get_breadcrumbs()` — SEO data
- `igny8()->schema->get_json_ld($post_id)` — schema markup
- `igny8()->linking->get_link_suggestions($post_id)` — internal link suggestions
- `igny8()->linking->get_cluster_navigation()` — cluster navigation data
- Term meta: `_igny8_term_content`, `_igny8_term_faq`, `_igny8_term_related_terms`
- Blueprint data: `get_option('igny8_sag_blueprint')` — full SAG structure

### Graceful Degradation
The theme checks `function_exists('igny8')` before calling any plugin API:
- **Without plugin:** Theme breadcrumbs, basic related content by category, no SAG features
- **With plugin standalone:** SEO breadcrumbs, schema, link suggestions, share buttons
- **With plugin connected:** Full SAG term pages, cluster navigation, blueprint visualization, rich term content

---

## 2. WHAT TO BUILD

### Overview
A Full Site Editing (FSE) block theme built for WordPress 5.9+ that provides:
- 7 custom post types (CPTs) optimized for service businesses, portfolios, and SaaS
- 9 custom taxonomies including SAG-mapped service categories and clusters
- Rich term landing page templates with 7-section layout
- Cluster hub template with dimensional navigation
- 15 landing page section types with 8 presets
- 50+ block patterns across 8 categories
- 13 custom Gutenberg blocks
- 5 site-type starter templates with demo content
- 6 interlinking display components
- WooCommerce integration when active

### Design System (theme.json)
- **Colors:** Primary palette (primary, light, dark, accent), neutrals (background, surface, text, text-secondary, border), semantic (success, warning, error, info)
- **Typography:** Heading + body font pairings from curated list. Sizes: xs, sm, base, lg, xl, 2xl, 3xl, 4xl
- **Spacing:** xs (0.25rem), sm (0.5rem), base (1rem), lg (1.5rem), xl (2rem), 2xl (3rem), 3xl (4rem)
- **Border Radius:** none, sm, base, lg, full
- **CSS:** BEM naming `.tn-block__element--modifier`, <35KB gzipped total
- **JS:** ES6+, vanilla (no jQuery on frontend), <15KB gzipped
- **Performance:** FCP <1.0s, LCP <1.5s, TBT <50ms, CLS <0.05, PageSpeed 95+ mobile

### 7 Custom Post Types

**CPT 1: `service`**
- Archive enabled, supports: title, editor, thumbnail, excerpt, revisions, page-attributes
- Taxonomies: `service_category`, `service_area`, `service_attribute`, `cluster`
- Rewrite: `/services/%service_category%/%postname%/`
- Templates: `single-service.html`, `archive-service.html`
- 10 meta fields:

| Meta Key | Type | Purpose |
|----------|------|---------|
| `_theme_service_price_range` | string | Price display ("$150 - $500") |
| `_theme_service_duration` | string | Time estimate ("2-4 hours") |
| `_theme_service_process_steps` | JSON | `[{step_number, title, desc, icon}]` |
| `_theme_service_outcomes` | JSON | `[{title, description}]` |
| `_theme_service_faqs` | JSON | `[{question, answer}]` |
| `_theme_service_cta_text` | string | CTA button text |
| `_theme_service_cta_url` | string | CTA button URL |
| `_theme_service_areas_served` | JSON | Geographic areas array |
| `_theme_service_gallery` | JSON | Attachment IDs array |
| `_theme_service_related_services` | JSON | Related service post IDs |

**CPT 2: `landing_page`**
- NO archive, does NOT support editor (section meta box instead)
- Rewrite: `/l/%postname%/`
- Template: `single-landing_page.html`
- Section-based rendering from `_theme_landing_sections` repeater meta (15 section types, see below)

**CPT 3: `portfolio`**
- Archive enabled, supports: title, editor, thumbnail, excerpt, revisions
- Taxonomies: `portfolio_category`, `portfolio_tag`, `service_category` (shared)
- Rewrite: `/portfolio/%portfolio_category%/%postname%/`
- Templates: `single-portfolio.html`, `archive-portfolio.html`
- 8 meta fields:

| Meta Key | Type | Purpose |
|----------|------|---------|
| `_theme_portfolio_client` | string | Client name |
| `_theme_portfolio_date` | string | YYYY-MM-DD |
| `_theme_portfolio_url` | string | Live project URL |
| `_theme_portfolio_results` | JSON | `[{metric, value, description}]` |
| `_theme_portfolio_technologies` | string | Comma-separated tech list |
| `_theme_portfolio_testimonial_id` | int | Linked testimonial post ID |
| `_theme_portfolio_gallery` | JSON | Attachment IDs array |
| `_theme_portfolio_before_after` | JSON | `{before_img, after_img}` |

**CPT 4: `team_member`**
- Archive enabled (team page), supports: title, editor, thumbnail
- Rewrite: `/team/%postname%/`
- Templates: `single-team-member.html`, `archive-team-member.html`
- 6 meta fields: `_theme_team_position`, `_theme_team_email`, `_theme_team_phone`, `_theme_team_social` (JSON: `{linkedin, twitter, facebook, website}`), `_theme_team_order` (int), `_theme_team_department`

**CPT 5: `testimonial`**
- Public: false (displayed via blocks/shortcodes only, no individual pages)
- Supports: title, editor, thumbnail
- 8 meta fields: `_theme_testimonial_author_name`, `_theme_testimonial_author_title`, `_theme_testimonial_company`, `_theme_testimonial_rating` (1-5 int), `_theme_testimonial_image` (attachment ID), `_theme_testimonial_featured` (bool), `_theme_testimonial_service_id` (linked service), `_theme_testimonial_product_id`

**CPT 6: `faq`**
- Archive enabled, supports: title, editor (title=question, editor=answer)
- Taxonomies: `faq_category`, `cluster`
- Rewrite: `/faq/%faq_category%/%postname%/`
- Templates: `single-faq.html`, `archive-faq.html`
- 2 meta fields: `_theme_faq_order` (int), `_theme_faq_schema_enabled` (bool)

**CPT 7: `documentation`**
- Archive enabled, hierarchical (parent/child docs)
- Supports: title, editor, thumbnail, page-attributes
- Taxonomies: `doc_category`
- Rewrite: `/docs/%doc_category%/%postname%/`
- Templates: `single-documentation.html`, `archive-documentation.html`
- 4 meta fields: `_theme_doc_sidebar_enabled` (bool), `_theme_doc_toc_enabled` (bool), `_theme_doc_last_reviewed` (date), `_theme_doc_related_docs` (JSON: post IDs)

> **Note:** WooCommerce taxonomies (`product_cat`, `product_tag`, `pa_*`) are NOT registered by theme. Theme provides rich templates for them. Theme registers `cluster` for `product` post type.

### 9 Custom Taxonomies

| # | Slug | For CPTs | Hierarchical | SAG Mapping | Rewrite |
|---|------|----------|-------------|-------------|---------|
| 1 | `service_category` | service, portfolio | Yes | Primary attribute | `/services/{slug}/` |
| 2 | `service_area` | service | Yes | Tertiary (geographic) | `/area/{slug}/` |
| 3 | `service_attribute` | service | No | Secondary attributes | `/attribute/{slug}/` |
| 4 | `portfolio_category` | portfolio | Yes | — | `/portfolio/{slug}/` |
| 5 | `portfolio_tag` | portfolio | No | — | `/tag/{slug}/` |
| 6 | `faq_category` | faq | Yes | Cluster assignment | `/faq/{slug}/` |
| 7 | `doc_category` | documentation | Yes | — | `/docs/{slug}/` |
| 8 | `cluster` | post, page, service, faq, product | No | Core cluster assignment | `/topic/{slug}/` |
| 9 | `topic_tag` | post, service, faq, documentation | No | Granular tagging | `/topic/{slug}/` |

### Term Landing Page Templates (7-Section Structure)

Every taxonomy term archive renders as a rich landing page:

| # | Section | Content |
|---|---------|---------|
| 1 | **Term Hero** | H1 (term name), description (from `_igny8_term_content` if active), breadcrumbs, post count |
| 2 | **Key Subtopics** | Grid of child term cards (if hierarchical + children exist) |
| 3 | **Content Grid** | Posts/services/products in term, filterable, paginated, layout options (grid 2/3/4 col, list) |
| 4 | **Related Terms** | Sibling terms or `_igny8_term_related_terms` from connected mode |
| 5 | **Cluster Cross-Links** | Related clusters sharing dimensional axes (if IGNY8 connected) |
| 6 | **FAQ Section** | Accordion from `_igny8_term_faq` or matching `faq_category` posts |
| 7 | **CTA** | Configurable per term or global default |

### Cluster Hub Template (`taxonomy-cluster.html`)

| # | Section | Content |
|---|---------|---------|
| 1 | **Cluster Hero** | H1, description, dimensional breadcrumb, content count |
| 2 | **Hub Content** | Pillar article from `_igny8_term_content` |
| 3 | **Supporting Content Grid** | Posts/services/products grouped by type |
| 4 | **Attribute Navigation** | Browse intersecting attributes via SAG data |
| 5 | **Related Clusters** | Cross-linking via SAG dimensional relationships |
| 6 | **FAQ** | Cluster-specific FAQ from `_igny8_term_faq` |
| 7 | **CTA** | Configurable CTA block |

### 6 Interlinking Display Components

| # | Template Part | Source | Fallback |
|---|--------------|--------|----------|
| 1 | `parts/related-content.html` | `_igny8_related_links` post meta | Category match, 3-4 cards |
| 2 | `parts/cluster-navigation.html` | `igny8()->linking->get_cluster_navigation()` | Same cluster term posts |
| 3 | `parts/attribute-browse.html` | Term archive sidebar pills/tags | All terms for taxonomy |
| 4 | `parts/breadcrumbs.html` | `igny8()->seo->get_breadcrumbs()` | Theme breadcrumb fallback |
| 5 | `parts/term-quick-links.html` | All terms assigned to post grouped by taxonomy | Standard tag list |
| 6 | `parts/child-term-grid.html` | Child terms with image/name/description/post count | `get_term_children()` |

### Landing Page System (15 Section Types)

| # | Type | Fields |
|---|------|--------|
| 1 | `hero` | headline, subheadline, CTA, background image/video/gradient |
| 2 | `features-grid` | columns 2/3/4, items: icon/title/description |
| 3 | `how-it-works` | numbered steps: title/description/icon |
| 4 | `social-proof` | testimonials: grid/slider/single layout |
| 5 | `pricing` | billing toggle monthly/annual, plans: features/price/CTA |
| 6 | `faq` | Q&A items, `schema_enabled` option for FAQPage JSON-LD |
| 7 | `cta-band` | headline, subheadline, CTA, background colors |
| 8 | `content-block` | title, WYSIWYG editor, image left/right, background |
| 9 | `stats-counter` | stats: number/suffix/label, animated counters |
| 10 | `team` | From `team_member` CPT or manual entries |
| 11 | `portfolio-grid` | From `portfolio` CPT |
| 12 | `contact-form` | Form shortcode, optional map, address block |
| 13 | `video-embed` | URL, poster image, autoplay, full-width options |
| 14 | `comparison-table` | columns, rows, highlight column option |
| 15 | `logo-bar` | Logo images, grid or horizontal scroll |

Section template files in `inc/landing-pages/sections/`: one PHP file per section type.

### 8 Landing Page Presets

| # | Preset | Section Order |
|---|--------|---------------|
| 1 | SaaS Product | hero → logo-bar → features → how-it-works → social-proof → pricing → faq → cta |
| 2 | Service Business | hero → features → content → stats → social-proof → team → contact-form → cta |
| 3 | Product Launch | hero → content → features → video → social-proof → pricing → faq → cta |
| 4 | Lead Generation | hero → features → social-proof → cta |
| 5 | Portfolio / Agency | hero → portfolio → how-it-works → social-proof → stats → contact-form |
| 6 | Event / Webinar | hero → content → features → social-proof → faq → cta |
| 7 | Cluster Hub | hero → content → features → faq → cta |
| 8 | Term Landing | hero → content → features → social-proof → faq → cta |

### 50+ Block Patterns (by Category)

| Category | Patterns |
|----------|----------|
| Heroes (4) | hero-centered, hero-split, hero-video-bg, hero-slider |
| Content (4) | features-3col, features-alternating, how-it-works, benefits-icons |
| Social Proof (4) | testimonials-grid, testimonials-slider, logo-bar, stats-row |
| Conversion (4) | cta-simple, cta-with-form, pricing-section, newsletter-signup |
| Services (3) | service-cards, service-list, service-with-sidebar |
| Portfolio (3) | portfolio-grid, portfolio-masonry, case-study-layout |
| Footers (3) | footer-4col, footer-centered, footer-minimal |
| Custom (13+) | pricing-table, feature-grid, testimonial-slider, stats-counter, team-grid, faq-accordion, cta-banner, logo-carousel, comparison-table, icon-box, service-grid, portfolio-showcase, doc-sidebar |

### 13 Custom Gutenberg Blocks

Registered in `inc/blocks/`, each with `block.json`, `edit.js`, `save.js`, `style.css`:

1. `pricing-table` — configurable pricing plans with toggle
2. `feature-grid` — icon + title + description grid
3. `testimonial-slider` — carousel from `testimonial` CPT
4. `stats-counter` — animated number counters
5. `team-grid` — from `team_member` CPT
6. `faq-accordion` — collapsible FAQ with optional FAQPage schema
7. `cta-banner` — full-width call-to-action band
8. `logo-carousel` — partner/client logo showcase
9. `comparison-table` — feature comparison matrix
10. `icon-box` — icon + heading + text block
11. `service-grid` — from `service` CPT (dynamic)
12. `portfolio-showcase` — from `portfolio` CPT (dynamic)
13. `doc-sidebar` — documentation navigation tree

### 5 Site-Type Starter Templates

Each includes full template files, sample CPT entries, sample taxonomy terms, demo images:

| # | Starter | Key Templates |
|---|---------|---------------|
| 1 | Blog | front-page, single.html, archive.html |
| 2 | SaaS | front-page, page-features.html, page-pricing.html, page-docs.html |
| 3 | Corporate | front-page, page-about.html, page-services.html, page-contact.html |
| 4 | eCommerce | front-page, archive-product.html, single-product.html |
| 5 | Portfolio | front-page, archive-portfolio.html, single-portfolio.html |

### WooCommerce Integration (when active)
- Register `cluster` taxonomy for `product` post type
- Rich category pages following term landing structure
- Product attribute support in templates
- Integration with IGNY8 schema (Product schema type from 02G)
- Template overrides: `archive-product.php`, `single-product.php`, `taxonomy-product_cat.php`, `content-product.php`

---

## 3. DATA MODELS & APIS

### No Custom Database Tables
The theme uses only WordPress native storage:
- **Post meta** — CPT meta fields (all `_theme_` prefixed)
- **Term meta** — Plugin term meta (all `_igny8_term_` prefixed, read-only from theme)
- **Options** — Theme settings via Customizer/theme.json

### Post Meta Summary (by CPT)

| CPT | Total Meta Fields | Prefix |
|-----|-------------------|--------|
| `service` | 10 | `_theme_service_` |
| `landing_page` | 1 (`_theme_landing_sections` repeater) | `_theme_landing_` |
| `portfolio` | 8 | `_theme_portfolio_` |
| `team_member` | 6 | `_theme_team_` |
| `testimonial` | 8 | `_theme_testimonial_` |
| `faq` | 2 | `_theme_faq_` |
| `documentation` | 4 | `_theme_doc_` |

### Plugin API Consumed (read-only)

| API Call | Purpose | Fallback Without Plugin |
|----------|---------|------------------------|
| `igny8()->seo->get_title()` | SEO title | `wp_title()` |
| `igny8()->seo->get_breadcrumbs()` | Breadcrumb HTML | Theme breadcrumb in `inc/breadcrumbs.php` |
| `igny8()->schema->get_json_ld($post_id)` | JSON-LD output | None (omitted) |
| `igny8()->linking->get_link_suggestions($post_id)` | Related content | Category-based `WP_Query` |
| `igny8()->linking->get_cluster_navigation()` | Cluster nav | Same-taxonomy term list |
| `get_term_meta($id, '_igny8_term_content')` | Term landing content | Term description |
| `get_term_meta($id, '_igny8_term_faq')` | Term FAQ data | `faq_category` posts query |
| `get_term_meta($id, '_igny8_term_related_terms')` | Related terms | Sibling terms |
| `get_option('igny8_sag_blueprint')` | SAG structure | Hidden (no SAG features) |

---

## 4. IMPLEMENTATION STEPS

### Theme Architecture

```
igny8-theme/
├── style.css                              # Theme header (required)
├── theme.json                             # Design system tokens, settings, styles
├── functions.php                          # Bootstrap, includes loader
├── screenshot.png                         # Theme screenshot (1200x900)
├── assets/
│   ├── css/                               # Compiled CSS (BEM, <35KB gzipped)
│   ├── js/                                # Vanilla ES6+ JS (<15KB gzipped)
│   ├── fonts/                             # Self-hosted font files
│   └── images/                            # Theme images, icons
├── inc/
│   ├── setup.php                          # Theme supports, menus, sidebars, image sizes
│   ├── cleanup.php                        # Remove WP bloat (emojis, embeds, etc.)
│   ├── enqueue.php                        # Conditional CSS/JS loading
│   ├── template-tags.php                  # Custom template tags
│   ├── breadcrumbs.php                    # Theme breadcrumb fallback (when plugin not active)
│   ├── walkers.php                        # Custom nav walkers
│   ├── customizer.php                     # Logo, colors, fonts, layout, social URLs, footer text
│   ├── theme-bridge.php                   # Communication layer with IGNY8 plugin
│   ├── cpt/
│   │   ├── register.php                   # All CPT registration
│   │   ├── service.php                    # service CPT config
│   │   ├── landing-page.php               # landing_page CPT config
│   │   ├── portfolio.php                  # portfolio CPT config
│   │   ├── team-member.php                # team_member CPT config
│   │   ├── testimonial.php                # testimonial CPT config
│   │   ├── faq.php                        # faq CPT config
│   │   └── documentation.php              # documentation CPT config
│   ├── taxonomies/
│   │   ├── register.php                   # All taxonomy registration
│   │   ├── service-category.php           # service_category config
│   │   ├── service-area.php               # service_area config
│   │   ├── service-attribute.php          # service_attribute config
│   │   ├── portfolio-category.php         # portfolio_category config
│   │   ├── portfolio-tag.php              # portfolio_tag config
│   │   ├── faq-category.php               # faq_category config
│   │   ├── doc-category.php               # doc_category config
│   │   ├── cluster.php                    # cluster taxonomy config
│   │   └── topic-tag.php                  # topic_tag config
│   ├── meta-fields/
│   │   ├── class-meta-box-base.php        # Base meta box class
│   │   ├── service-meta.php               # service CPT meta handler
│   │   ├── landing-page-meta.php          # landing_page section repeater
│   │   ├── portfolio-meta.php             # portfolio CPT meta handler
│   │   ├── team-member-meta.php           # team_member meta handler
│   │   ├── testimonial-meta.php           # testimonial meta handler
│   │   ├── faq-meta.php                   # faq meta handler
│   │   └── documentation-meta.php         # documentation meta handler
│   ├── landing-pages/
│   │   ├── register-cpt.php               # Landing page CPT specifics
│   │   ├── meta-boxes.php                 # Section repeater meta box
│   │   ├── presets.php                    # 8 landing page presets
│   │   ├── render.php                     # Section rendering engine
│   │   └── sections/                      # 15 section PHP 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
│   │       ├── comparison-table.php
│   │       └── logo-bar.php
│   ├── interlinking/
│   │   ├── related-content.php            # After-post related content
│   │   ├── cluster-navigation.php         # Cluster nav component
│   │   ├── attribute-browse.php           # Attribute browsing sidebar
│   │   ├── breadcrumbs-component.php      # SAG-aware breadcrumbs
│   │   ├── term-quick-links.php           # Post sidebar term links
│   │   └── child-term-grid.php            # Child term card grid
│   ├── blocks/                            # 13 custom block registrations
│   │   ├── pricing-table/
│   │   ├── feature-grid/
│   │   ├── testimonial-slider/
│   │   ├── stats-counter/
│   │   ├── team-grid/
│   │   ├── faq-accordion/
│   │   ├── cta-banner/
│   │   ├── logo-carousel/
│   │   ├── comparison-table/
│   │   ├── icon-box/
│   │   ├── service-grid/
│   │   ├── portfolio-showcase/
│   │   └── doc-sidebar/
│   └── patterns/
│       ├── register.php                   # Pattern category + registration
│       ├── heroes/
│       ├── content/
│       ├── social-proof/
│       ├── conversion/
│       ├── services/
│       ├── portfolio/
│       └── footers/
├── templates/                             # FSE templates (20+)
│   ├── index.html
│   ├── home.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   ├── single-service.html
│   ├── single-portfolio.html
│   ├── single-landing_page.html
│   ├── single-documentation.html
│   ├── single-faq.html
│   ├── single-team-member.html
│   ├── archive-service.html
│   ├── archive-portfolio.html
│   ├── archive-faq.html
│   ├── archive-documentation.html
│   ├── archive-team-member.html
│   ├── taxonomy-service_category.html
│   ├── taxonomy-service_area.html
│   ├── taxonomy-service_attribute.html
│   ├── taxonomy-cluster.html
│   ├── taxonomy-faq_category.html
│   ├── taxonomy-product_cat.html          # WooCommerce
│   ├── taxonomy-product_tag.html          # WooCommerce
│   ├── search.html
│   ├── 404.html
│   └── starters/                          # 5 starter template sets
├── parts/                                 # FSE template parts (20+)
│   ├── header.html
│   ├── header-transparent.html
│   ├── header-minimal.html
│   ├── footer.html
│   ├── footer-minimal.html
│   ├── sidebar.html
│   ├── sidebar-docs.html
│   ├── post-meta.html
│   ├── author-box.html
│   ├── comments.html
│   ├── pagination.html
│   ├── related-content.html
│   ├── cluster-navigation.html
│   ├── attribute-browse.html
│   ├── breadcrumbs.html
│   ├── term-quick-links.html
│   ├── child-term-grid.html
│   ├── term-hero.html
│   ├── term-content.html
│   └── term-faq.html
└── woocommerce/                           # WooCommerce template overrides
    ├── archive-product.php
    ├── single-product.php
    ├── taxonomy-product_cat.php
    ├── content-product.php
    ├── cart/
    ├── checkout/
    └── myaccount/
```

### Build Sequence

**Phase 1: Foundation (Days 1-3)**
1. Create `style.css` header, `theme.json` design tokens, `functions.php` bootstrap
2. Build `inc/setup.php` — theme supports, menus, sidebars, image sizes
3. Build `inc/cleanup.php` — remove WP bloat (emojis, embed scripts, etc.)
4. Build `inc/enqueue.php` — conditional CSS/JS loading
5. Build `inc/theme-bridge.php` — plugin detection + API wrapper
6. Build `inc/customizer.php` — logo, colors, fonts, layout options

**Phase 2: CPTs + Taxonomies (Days 4-7)**
1. Register all 7 CPTs in `inc/cpt/` (7 config files + register.php)
2. Register all 9 taxonomies in `inc/taxonomies/` (9 config files + register.php)
3. Build `inc/meta-fields/class-meta-box-base.php` + 7 per-CPT meta handlers
4. Build basic FSE templates for all CPTs: single-*.html, archive-*.html

**Phase 3: Term Landing Pages + Cluster Hub (Days 8-10)**
1. Build 7-section term landing page template structure
2. Build `taxonomy-cluster.html` hub template
3. Build all taxonomy-*.html templates
4. Build 6 interlinking components in `inc/interlinking/`
5. Build template parts: term-hero, term-content, term-faq, child-term-grid, etc.

**Phase 4: Landing Page System (Days 11-14)**
1. Build section repeater meta box for `landing_page` CPT
2. Build 15 section PHP templates in `inc/landing-pages/sections/`
3. Build section rendering engine (`inc/landing-pages/render.php`)
4. Build 8 landing page presets (`inc/landing-pages/presets.php`)

**Phase 5: Blocks + Patterns (Days 15-19)**
1. Register 13 custom Gutenberg blocks with `block.json` + edit/save JS
2. Register 50+ block patterns across 8 categories
3. Build `inc/breadcrumbs.php` fallback
4. Build `inc/walkers.php` for nav menus
5. Build `inc/template-tags.php` for template helper functions

**Phase 6: Starters + WooCommerce (Days 20-23)**
1. Build 5 site-type starter template sets with demo content
2. Build WooCommerce template overrides (archive-product, single-product, taxonomy-product_cat)
3. Register `cluster` taxonomy for `product` post type when WooCommerce active

**Phase 7: Polish (Days 24-26)**
1. CSS optimization — ensure <35KB gzipped total
2. JS optimization — ensure <15KB gzipped, vanilla ES6+
3. Performance audit — meet FCP <1.0s, LCP <1.5s, TBT <50ms targets
4. Accessibility review — ARIA labels, keyboard nav, focus states
5. i18n pass — all strings via `igny8-theme` text domain
6. Screenshot + readme

---

## 5. ACCEPTANCE CRITERIA

### CPTs & Taxonomies
- [ ] All 7 CPTs registered with correct supports, rewrite rules, and templates
- [ ] All 9 taxonomies registered with correct hierarchy, post type assignments, and rewrites
- [ ] All CPT meta boxes render and save correctly
- [ ] `service` CPT displays with all 10 meta fields in single-service template
- [ ] `landing_page` CPT renders sections from repeater meta
- [ ] `portfolio` CPT shows results, gallery, before/after
- [ ] `faq` CPT renders as FAQ with optional schema

### Term Landing Pages
- [ ] Every taxonomy term archive renders 7-section landing page
- [ ] Term hero shows name, description (from `_igny8_term_content` or fallback), post count
- [ ] Child term grid, content grid, related terms, FAQ accordion all render
- [ ] Cluster cross-links appear when IGNY8 plugin connected
- [ ] Graceful fallback when plugin is not active

### Cluster Hub
- [ ] `taxonomy-cluster.html` renders hub with pillar content, supporting grid, attribute nav
- [ ] Dimensional navigation works (browse intersecting attributes)
- [ ] Related clusters cross-link correctly

### Landing Pages
- [ ] All 15 section types render correctly
- [ ] All 8 presets pre-populate correct section order
- [ ] Section repeater meta box allows add/remove/reorder sections
- [ ] FAQ section generates FAQPage schema when `schema_enabled` is true

### Blocks & Patterns
- [ ] All 13 custom blocks registered and functional in block editor
- [ ] 50+ patterns available in pattern inserter, categorized correctly
- [ ] Dynamic blocks (service-grid, portfolio-showcase, doc-sidebar) query correct CPTs

### Interlinking Components
- [ ] Related content shows `_igny8_related_links` data or category fallback
- [ ] Cluster navigation renders when plugin provides data
- [ ] Breadcrumbs use plugin or theme fallback
- [ ] All 6 template parts render without errors

### Starters & WooCommerce
- [ ] All 5 starter templates import with demo content
- [ ] WooCommerce product templates render with cluster taxonomy
- [ ] Product category archives follow term landing structure

### Performance & Quality
- [ ] CSS <35KB gzipped, JS <15KB gzipped
- [ ] PageSpeed Insights 95+ mobile
- [ ] FCP <1.0s, LCP <1.5s, TBT <50ms, CLS <0.05
- [ ] All strings translatable via `igny8-theme` text domain
- [ ] Keyboard navigation works on all interactive elements
- [ ] ARIA labels on all custom blocks and components

---

## 6. CLAUDE CODE INSTRUCTIONS

### Context Requirements
Before starting implementation:
1. Read 03A (plugin standalone) — understand `igny8()` public API, module methods
2. Read 03B (plugin connected) — understand term meta keys, blueprint data structure
3. Read 01A (SAG Data Foundation) — understand SAGCluster, SAGAttribute relationships
4. Read 01B (SAG Blueprint Engine) — understand dimension/attribute hierarchy

### Execution Order
```
Foundation → CPTs+Taxonomies → Term Landing+Cluster Hub → Landing Page System → Blocks+Patterns → Starters+WooCommerce → Polish
```

### Critical Rules
1. **FSE block theme** — use `templates/` and `parts/` directories with HTML files, not classic PHP templates
2. **theme.json** — all design tokens defined here, not in CSS variables directly
3. **No jQuery on frontend** — vanilla ES6+ only, jQuery allowed in admin only
4. **Conditional plugin features** — always check `function_exists('igny8')` before plugin API calls
5. **All IDs are integers** — IGNY8 content IDs, cluster IDs, term IDs are all integers (BigAutoField)
6. **Meta prefix** — theme meta uses `_theme_` prefix, plugin meta uses `_igny8_` prefix (read-only from theme)
7. **Text domain** — `igny8-theme` (different from plugin's `igny8` domain)
8. **Sanitize/escape** — all meta saves via `sanitize_text_field()` / `wp_kses_post()`, all output via `esc_html()` / `esc_attr()` / `esc_url()`
9. **Performance first** — aim for zero JS on pages that don't need it, conditional CSS loading

### File Creation Order
```
1. style.css + theme.json + functions.php (foundation)
2. inc/setup.php + inc/cleanup.php + inc/enqueue.php
3. inc/theme-bridge.php + inc/customizer.php
4. inc/cpt/register.php + 7 CPT files
5. inc/taxonomies/register.php + 9 taxonomy files
6. inc/meta-fields/class-meta-box-base.php + 7 meta handlers
7. templates/ (20+ FSE template files)
8. parts/ (20+ template part files)
9. inc/interlinking/ (6 component files)
10. inc/landing-pages/ (15 section templates + render engine + presets)
11. inc/blocks/ (13 block directories)
12. inc/patterns/ (50+ patterns)
13. woocommerce/ (template overrides)
14. templates/starters/ (5 starter sets)
15. inc/breadcrumbs.php + inc/walkers.php + inc/template-tags.php
```

### Cross-References

| Doc | Relationship |
|-----|-------------|
| 03A WP Plugin Standalone | Plugin API: `igny8()->seo`, `igny8()->schema`, `igny8()->linking` consumed by theme |
| 03B WP Plugin Connected | Connected mode provides: term meta, blueprint data, cluster navigation |
| 01A SAG Data Foundation | SAGCluster → `cluster` taxonomy, SAGAttribute → `service_category`/`service_attribute`/`service_area` |
| 01B SAG Blueprint Engine | Blueprint dimensions → theme taxonomies, blueprint clusters → hub pages |
| 02D Linker Internal | Link suggestions feed `parts/related-content.html` via plugin API |
| 02G Rich Schema SERP | Schema types feed Module 2 which theme triggers via `igny8()->schema` |
| 03D Toolkit Plugin | Toolkit complements theme (forms, performance, security) |