igny8/v2/V2-Execution-Docs/04C-pricing-launch.md

# IGNY8 Phase 4: Pricing & Launch (04C)
## Feature Gating, Plan Matrix, WP.org Submission, Go-to-Market, Migration

**Document Version:** 1.0
**Date:** 2026-03-23
**Phase:** IGNY8 Phase 4 — Business Layer
**Status:** Build Ready
**Source of Truth:** Codebase at `/data/app/igny8/`
**Audience:** Claude Code, Backend Developers, Frontend Developers, Product

---

## 1. CURRENT STATE

### Current Plan Structure
- 4 plans live: Free ($0), Starter ($49), Growth ($149), Scale ($349)
- Stripe + PayPal integrated for payment processing
- Plan model exists in `billing` app with basic feature limits (sites, credits)
- Feature gating is minimal — no granular per-feature capability matrix
- No `plan_features` JSONField on Plan

### No WordPress.org Plugin Submission
- WP plugin built in 03A but not submitted to WP.org directory
- No SVN deploy pipeline configured
- No readme.txt in WP.org format
- No plugin banner/icon assets

### No Go-to-Market Strategy Implemented
- Current clients are direct Alorig relationships
- No organic acquisition funnel from WP.org
- No marketing automation for plan upgrade nudges
- No add-on purchase flow for managed services

### Phase 4A + 4B Complete
- `ManagedServiceSubscription` model (04A) — tiers, pricing, monthly targets
- `BacklinkServiceOrder` model (04A) — packages, pricing, margin tracking
- `ServiceReport` model (04B) — automated reports with PDF generation
- `AgencyBranding` model (04B) — white-label branding config
- All Phase 2 features built — each needs plan-level gating

---

## 2. WHAT TO BUILD

### Updated Plan Feature Matrix

Core SaaS plan prices unchanged. All V2 features gated by plan level:

| Feature | Free | Starter ($49) | Growth ($149) | Scale ($349) |
|---------|------|---------------|---------------|--------------|
| Sites | 1 | 3 | 10 | Unlimited |
| Credits/month | 100 | 1,000 | 5,000 | 25,000 |
| SAG Blueprint | Quick mode only | Quick + Detailed | Full | Full |
| Content Types | Post only | Post + Page | All types | All types |
| Taxonomy Content (02B) | — | — | Yes | Yes |
| GSC Integration (02C) | — | Basic (analytics) | Full (+ indexing) | Full |
| Internal Linker (02D) | — | Audit only | Audit + auto-insert | Full + remediation |
| External Backlinks (02E) | — | — | Self-service | Self-service + API |
| Optimizer (02F) | — | Basic analysis | Full rewrite | Full + batch |
| Rich Schema (02G) | Basic (Article) | 5 types | All 10 types | All + retroactive |
| Socializer (02H) | — | 2 platforms | All platforms | All + auto-schedule |
| Video Creator (02I) | — | — | Short-form only | All formats |
| Ahrefs Integration (04A) | — | — | Read-only metrics | Full (verify + prospect) |
| Backlink Indexing (04A) | — | — | — | Included |
| Reports (04B) | — | — | Monthly PDF | Weekly + custom |
| White-Label (04B) | — | — | — | Yes |
| API Access | — | — | Read-only | Full CRUD |
| Managed Services (04A) | — | — | Can purchase Lite | Can purchase Lite/Pro |

### Feature Flag System

**Approach:** Add `plan_features` JSONField on existing `Plan` model.

**JSON structure per plan:**
```json
{
    "sag_mode": "quick",
    "content_types": ["post"],
    "taxonomy_content": false,
    "gsc_level": "none",
    "linker_level": "none",
    "backlinks_level": "none",
    "optimizer_level": "none",
    "schema_types": 0,
    "socializer_platforms": 0,
    "video_level": "none",
    "ahrefs_level": "none",
    "backlink_indexing": false,
    "report_level": "none",
    "white_label": false,
    "api_access": "none",
    "managed_services": "none"
}
```

**Feature level hierarchies:**
```python
LEVEL_HIERARCHY = {
    "sag_mode": ["quick", "detailed", "full"],
    "gsc_level": ["none", "basic", "full"],
    "linker_level": ["none", "audit", "auto", "full"],
    "backlinks_level": ["none", "self_service", "self_service_api"],
    "optimizer_level": ["none", "basic", "full", "batch"],
    "video_level": ["none", "short", "all"],
    "ahrefs_level": ["none", "readonly", "full"],
    "report_level": ["none", "monthly", "weekly_custom"],
    "api_access": ["none", "readonly", "full"],
    "managed_services": ["none", "lite", "lite_pro"],
}
```

**Feature gate checking pattern:**
```python
class FeatureGateService:
    @staticmethod
    def check_feature(account, feature, required_level):
        plan = account.subscription.plan
        features = plan.plan_features or {}
        current = features.get(feature, "none")
        hierarchy = LEVEL_HIERARCHY.get(feature)
        if hierarchy is None:
            # Boolean or list feature — direct comparison
            return bool(current)
        return hierarchy.index(current) >= hierarchy.index(required_level)
```

**Decorator for ViewSets:**
```python
def require_feature(feature, required_level):
    def decorator(view_func):
        @wraps(view_func)
        def wrapper(self, request, *args, **kwargs):
            account = request.user.account
            if not FeatureGateService.check_feature(account, feature, required_level):
                return Response(
                    {"detail": f"Feature '{feature}' requires plan upgrade."},
                    status=403
                )
            FeatureGateService.log_usage(account, feature, required_level, True, request.path)
            return view_func(self, request, *args, **kwargs)
        return wrapper
    return decorator
```

**Usage example:**
```python
class InternalLinkViewSet(viewsets.ModelViewSet):
    @require_feature('linker_level', 'auto')
    def auto_insert(self, request):
        ...
```

### Managed Services Add-On Pricing (in Billing Flow)

| Add-On | Price | Available To |
|--------|-------|-------------|
| Managed Lite | $100/site/month | Growth + Scale plans |
| Managed Pro | $399/site/month | Scale plan only |
| Backlink Package (Starter) | $800–$1,500/month | Growth + Scale |
| Backlink Package (Growth) | $2,000–$4,000/month | Growth + Scale |
| Backlink Package (Authority) | $4,000–$8,000/month | Scale only |
| Indexing Boost (standalone) | $0.15/URL | Growth + Scale |

Add-ons are purchased via existing Stripe/PayPal subscription modification. Each add-on creates related model records:
- Managed services → `ManagedServiceSubscription` (04A)
- Backlink packages → `BacklinkServiceOrder` (04A)
- Indexing boost → credit balance increase for indexing operations

### WordPress.org Plugin Submission

**Plugin identity:** `igny8-seo` (standalone plugin from 03A, rebranded for WP.org)
**Version:** 2.0.0
**License:** GPL v2+

**Submission checklist (10 items):**

| # | Requirement | Details |
|---|------------|---------|
| 1 | Input sanitization | All user inputs sanitized with `sanitize_text_field()`, `intval()`, `wp_kses_post()` |
| 2 | Output escaping | All outputs escaped with `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()` |
| 3 | Nonce verification | All form submissions verified with `wp_verify_nonce()` / `check_admin_referer()` |
| 4 | No unauthorized external calls | Phone-home disabled by default, Settings API toggle for optional usage analytics |
| 5 | GPL v2+ license | `LICENSE` file in plugin root, `License: GPLv2 or later` in plugin header |
| 6 | `readme.txt` | WP.org formatted: short description, installation, FAQ, changelog, screenshots |
| 7 | Assets | Banner 1544×500 + 772×250, icon 256×256 + 128×128, 8+ screenshots |
| 8 | Translation-ready | All strings in `__()`, `_e()`, `esc_html__()` with `igny8` text domain |
| 9 | No minified JS without source | Unminified versions included alongside minified |
| 10 | Security hardening | `ABSPATH` check at top of every PHP file, no `eval()`, no `file_get_contents()` for remote |

**Privacy compliance:**
- No tracking without consent
- No storing user IPs (hash only if needed)
- Privacy policy section in readme.txt

**Post-approval setup:**
- SVN deploy pipeline: GitHub tag → GitHub Actions → WP.org SVN
- Auto-deploy on version tag push
- Update checker: `/api/v1/plugins/igny8-seo/check-update/` for connected users

**Review timeline:** Typically 1–4 weeks for initial WP.org review.

### Go-to-Market Strategy

**5 Target Audiences:**

| # | Audience | How They Find Us | Conversion Path |
|---|----------|-----------------|----------------|
| 1 | WordPress site owners | WP.org plugin directory search | Free plugin → Setup Wizard → Free Plan → Upgrade |
| 2 | SEO agencies | Direct outreach, white-label pitch | Demo → Managed Pro → Backlink packages |
| 3 | Content creators/bloggers | WP.org + SEO community + content about SAG | Free → Growth for full content pipeline |
| 4 | eCommerce stores | WP.org (WooCommerce integration mention) | Free → Growth for product schema + services |
| 5 | Local businesses | WP.org (LocalBusiness schema, service areas) | Free → Starter for GSC + schema |

**Acquisition Funnel:**
```
WP.org Plugin (free) → Install → Setup Wizard →
  → Free Plan (100 credits) → Experience value →
  → Upgrade to Starter/Growth/Scale →
  → Optional: Purchase Managed Services add-on →
  → Optional: Purchase Backlink Packages
```

### Launch Sequence

| Step | Action | Timing |
|------|--------|--------|
| 1 | Enable `managed_services_enabled` flag in staging | Week 1 |
| 2 | Onboard 2–3 existing Alorig clients as beta managed service subscribers | Week 1–2 |
| 3 | Test full cycle: onboarding → content → backlinks → indexing → reporting | Week 2–3 |
| 4 | Fix issues from beta testing | Week 3 |
| 5 | Submit WP.org plugin (parallel with beta testing) | Week 2 |
| 6 | Enable feature flags in production | Week 3–4 |
| 7 | Update pricing page on marketing site | Week 4 |
| 8 | Send announcement email to existing users | Week 4 |
| 9 | Begin WP.org organic acquisition (post-approval) | Ongoing |

### Existing User Migration

**Principle:** Nothing existing breaks. New feature gates apply to new features only.

**Migration steps:**
1. Run one-time `migrate_plan_features` Celery task
2. Populate `plan_features` JSONField on all 4 existing Plan records with appropriate values
3. Existing users retain current plan pricing (grandfathered)
4. Existing credits + billing cycles unchanged
5. Users gain access to new V2 features according to their plan level

**Migration data per plan:**
```python
PLAN_FEATURE_DEFAULTS = {
    "free": {
        "sag_mode": "quick",
        "content_types": ["post"],
        "taxonomy_content": False,
        "gsc_level": "none",
        "linker_level": "none",
        "backlinks_level": "none",
        "optimizer_level": "none",
        "schema_types": 0,
        "socializer_platforms": 0,
        "video_level": "none",
        "ahrefs_level": "none",
        "backlink_indexing": False,
        "report_level": "none",
        "white_label": False,
        "api_access": "none",
        "managed_services": "none",
    },
    "starter": {
        "sag_mode": "detailed",
        "content_types": ["post", "page"],
        "taxonomy_content": False,
        "gsc_level": "basic",
        "linker_level": "audit",
        "backlinks_level": "none",
        "optimizer_level": "basic",
        "schema_types": 5,
        "socializer_platforms": 2,
        "video_level": "none",
        "ahrefs_level": "none",
        "backlink_indexing": False,
        "report_level": "none",
        "white_label": False,
        "api_access": "none",
        "managed_services": "none",
    },
    "growth": {
        "sag_mode": "full",
        "content_types": "all",
        "taxonomy_content": True,
        "gsc_level": "full",
        "linker_level": "auto",
        "backlinks_level": "self_service",
        "optimizer_level": "full",
        "schema_types": 10,
        "socializer_platforms": "all",
        "video_level": "short",
        "ahrefs_level": "readonly",
        "backlink_indexing": False,
        "report_level": "monthly",
        "white_label": False,
        "api_access": "readonly",
        "managed_services": "lite",
    },
    "scale": {
        "sag_mode": "full",
        "content_types": "all",
        "taxonomy_content": True,
        "gsc_level": "full",
        "linker_level": "full",
        "backlinks_level": "self_service_api",
        "optimizer_level": "batch",
        "schema_types": "all_retroactive",
        "socializer_platforms": "all_auto",
        "video_level": "all",
        "ahrefs_level": "full",
        "backlink_indexing": True,
        "report_level": "weekly_custom",
        "white_label": True,
        "api_access": "full",
        "managed_services": "lite_pro",
    },
}
```

---

## 3. DATA MODELS & APIS

### Modified Models

**`Plan` (billing app)** — add field:

| Field | Type | Description |
|-------|------|-------------|
| `plan_features` | JSONField(default=dict) | Feature capability matrix per plan |

No new table — existing `igny8_plans` table gets new column.

### New Models

**`FeatureUsageLog`** (extends `AccountBaseModel`, billing app)
| Field | Type | Description |
|-------|------|-------------|
| `feature` | CharField(max_length=50) | Feature key checked (e.g., `linker_level`) |
| `required_level` | CharField(max_length=30) | Level that was required |
| `current_level` | CharField(max_length=30) | Level user's plan has |
| `was_allowed` | BooleanField | Whether access was granted |
| `endpoint` | CharField(max_length=200) | API endpoint that triggered the check |
| `timestamp` | DateTimeField(auto_now_add=True) | When the check happened |

Table: `igny8_feature_usage_log`

Purpose: Track which features users hit gates on → inform pricing decisions and identify upgrade opportunities.

### API Endpoints

All under `/api/v1/`:

**Feature Gates:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/billing/features/` | Current account's available features |
| GET | `/billing/features/check/{feature}/` | Check specific feature access |

**Plan Management (admin only):**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/billing/plans/` | List all plans with features |
| PUT | `/billing/plans/{id}/features/` | Update plan feature matrix |

**Add-On Purchases:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/billing/add-ons/` | List available add-ons for current plan |
| POST | `/billing/add-ons/managed-service/` | Purchase managed service add-on |
| POST | `/billing/add-ons/backlink-package/` | Purchase backlink package |
| POST | `/billing/add-ons/indexing-boost/` | Purchase indexing credits |

**WP.org Plugin (public, no auth required):**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/plugins/igny8-seo/info/` | Plugin info for WP update checker |
| GET | `/plugins/igny8-seo/download/` | Download latest ZIP |
| GET | `/plugins/igny8-seo/check-update/` | Version check endpoint |

### Celery Tasks

| Task | Schedule | Purpose |
|------|----------|---------|
| `migrate_plan_features` | One-time | Populate `plan_features` on existing Plan records |
| `sync_wporg_stats` | Daily | Fetch WP.org download/rating stats |
| `feature_usage_report` | Weekly | Aggregate FeatureUsageLog for product decisions |

### Services

| Service | Purpose |
|---------|---------|
| `FeatureGateService` | `check_feature()`, `get_plan_features()`, `log_usage()` |
| `AddOnPurchaseService` | Process add-on purchases via existing Stripe/PayPal integration |
| `WPOrgDeployService` | SVN deploy pipeline config for WP.org (GitHub Actions) |

---

## 4. IMPLEMENTATION STEPS

### Build Sequence

**Week 1: Feature Gate System**
1. Add `plan_features` JSONField to `Plan` model + migration
2. Create `FeatureUsageLog` model + migration
3. Build `FeatureGateService` with `check_feature()`, `log_usage()`
4. Build `@require_feature()` decorator
5. Create feature check API endpoints (`/billing/features/`)
6. Write `migrate_plan_features` one-time task with `PLAN_FEATURE_DEFAULTS`

**Week 2: Plan Feature Integration**
1. Apply `@require_feature()` decorator to all Phase 2 module ViewSets:
   - 02B taxonomy content endpoints → `taxonomy_content`
   - 02C GSC endpoints → `gsc_level`
   - 02D internal linker endpoints → `linker_level`
   - 02E external backlinks endpoints → `backlinks_level`
   - 02F optimizer endpoints → `optimizer_level`
   - 02G schema endpoints → `schema_types`
   - 02H socializer endpoints → `socializer_platforms`
   - 02I video endpoints → `video_level`
   - 04A Ahrefs endpoints → `ahrefs_level`
   - 04A indexing endpoints → `backlink_indexing`
   - 04B report endpoints → `report_level`
   - 04B white-label endpoints → `white_label`
2. Build add-on purchase endpoints using existing Stripe/PayPal
3. Build plan admin feature update endpoint

**Week 3: WP.org Submission + Launch**
1. Build WP.org plugin info/download/check-update public endpoints
2. Prepare plugin for WP.org: readme.txt, assets, security audit
3. Set up GitHub Actions → WP.org SVN deploy pipeline
4. Submit plugin to WP.org review queue
5. Run `migrate_plan_features` on production
6. Update marketing site pricing page

### Frontend Changes

**Billing pages (existing):**
- Update plan comparison table to show all V2 features
- Add "Feature Unavailable" overlay when gated feature accessed on lower plan
- Add upgrade CTA buttons inline with gated features

**Add-on purchase flow:**
```
frontend/src/pages/Billing/
├── AddOns.tsx                     # Available add-ons for current plan
│   ├── ManagedServiceCard.tsx     # Lite/Pro tier selection → purchase
│   ├── BacklinkPackageCard.tsx    # Package selection → purchase
│   └── IndexingBoostCard.tsx      # Quantity slider → purchase
└── PlanComparison.tsx             # Updated with all V2 features
```

**Zustand store addition:**
```typescript
// Extend existing billing store
interface BillingState {
  // ... existing fields
  planFeatures: PlanFeatures | null
  addOns: AddOn[]
  fetchPlanFeatures: () => Promise<void>
  purchaseAddOn: (type: string, params: AddOnParams) => Promise<void>
  checkFeature: (feature: string) => boolean
}
```

**Feature gate UI pattern:**
```tsx
// Reusable component for gated features
const FeatureGate: React.FC<{ feature: string; requiredLevel: string }> = ({
  feature, requiredLevel, children
}) => {
  const { checkFeature } = useBillingStore()
  if (!checkFeature(feature)) {
    return <UpgradePrompt feature={feature} requiredLevel={requiredLevel} />
  }
  return <>{children}</>
}
```

---

## 5. ACCEPTANCE CRITERIA

### Feature Gate System
- [ ] `plan_features` JSONField added to `Plan` model
- [ ] `FeatureGateService.check_feature()` correctly evaluates level hierarchy
- [ ] `@require_feature()` decorator returns 403 with upgrade message for insufficient plan
- [ ] `FeatureUsageLog` records all gate checks (allowed and denied)
- [ ] All Phase 2 module ViewSets decorated with appropriate feature gates
- [ ] `/billing/features/` returns current account's feature matrix
- [ ] `/billing/features/check/{feature}/` returns allowed/denied for specific feature

### Plan Feature Defaults
- [ ] Free plan: quick SAG, post only, no V2 features
- [ ] Starter plan: detailed SAG, post + page, basic GSC, audit linker, basic optimizer, 5 schema types, 2 social platforms
- [ ] Growth plan: full SAG, all content types, full GSC, auto linker, full optimizer, all schema, all social, short video, readonly Ahrefs, monthly reports, readonly API, can purchase Lite managed
- [ ] Scale plan: everything at maximum level including white-label, weekly reports, full API, both managed tiers

### Add-On Purchases
- [ ] Add-on availability respects plan level (e.g., Authority package only for Scale)
- [ ] Purchase creates appropriate model records (ManagedServiceSubscription, BacklinkServiceOrder)
- [ ] Stripe/PayPal subscription modification works for recurring add-ons
- [ ] One-time purchases (indexing boost) add credits correctly

### Migration
- [ ] `migrate_plan_features` task populates all 4 existing plans correctly
- [ ] Existing users see no change in accessible features they already had
- [ ] New V2 features available according to plan level after migration

### WP.org Plugin
- [ ] `/plugins/igny8-seo/info/` returns valid plugin info JSON
- [ ] `/plugins/igny8-seo/check-update/` returns latest version for WP update checker
- [ ] `/plugins/igny8-seo/download/` serves latest plugin ZIP
- [ ] readme.txt passes WP.org validator
- [ ] All 10 submission checklist items verified

### Frontend
- [ ] Plan comparison page shows all V2 features by plan
- [ ] `FeatureGate` component shows upgrade prompt for gated features
- [ ] Add-on purchase flow completes end-to-end
- [ ] Feature denied state shows clear upgrade path

---

## 6. CLAUDE CODE INSTRUCTIONS

### Context Requirements
1. Read existing `Plan` model in billing app — understand current fields before adding `plan_features`
2. Read existing billing ViewSets — understand current plan/subscription endpoints
3. Read all Phase 2 execution docs (02B–02I) — identify every ViewSet that needs `@require_feature()`
4. Read 04A (Managed Services) — subscription + order models for add-on purchase integration
5. Read 04B (Whitelabel Reporting) — report + branding endpoints to gate by plan
6. Read 03A (WP Plugin Standalone) — plugin structure for WP.org submission preparation

### Execution Order
```
plan_features migration → FeatureGateService → @require_feature decorator →
Apply to all Phase 2 ViewSets → Add-on purchase endpoints →
WP.org public endpoints → Frontend feature gate component →
migrate_plan_features task → Launch checklist
```

### Critical Rules
1. **All IDs are integers** — BigAutoField PKs
2. **Model names PLURAL** — consistent with existing codebase
3. **Table prefix** — `igny8_` for all tables
4. **Billing app** — `Plan` modification and `FeatureUsageLog` go in existing billing app
5. **Frontend** — `.tsx` files, Zustand stores
6. **Decorator stacks** — `@require_feature()` stacks with existing `@permission_classes` and DRF auth
7. **No breaking changes** — existing Plan records must work before and after migration
8. **Celery app** — `igny8_core` for all tasks
9. **Add-on pricing** — use existing Stripe Product/Price objects, create new ones only for new add-ons
10. **WP.org endpoints** — public (no auth), rate-limited, no sensitive data exposed

### Cross-References

| Doc | Relationship |
|-----|-------------|
| 04A Managed Services | Add-on purchase creates ManagedServiceSubscription + BacklinkServiceOrder |
| 04B Whitelabel Reporting | Report + white-label features gated by plan level |
| 02B Taxonomy Content | Gated by `taxonomy_content` boolean |
| 02C GSC Integration | Gated by `gsc_level` (none/basic/full) |
| 02D Linker Internal | Gated by `linker_level` (none/audit/auto/full) |
| 02E Linker External | Gated by `backlinks_level` (none/self_service/self_service_api) |
| 02F Optimizer | Gated by `optimizer_level` (none/basic/full/batch) |
| 02G Rich Schema | Gated by `schema_types` (0/5/10/all_retroactive) |
| 02H Socializer | Gated by `socializer_platforms` (0/2/all/all_auto) |
| 02I Video Creator | Gated by `video_level` (none/short/all) |
| 03A WP Plugin Standalone | Plugin submitted to WP.org, update checker endpoints |
| Billing App (existing) | Plan model modified, Stripe/PayPal integration for add-ons |