# ClearConsent — Freemius setup checklist

Wiring licensing so Free/Pro/Agency work for real customers and `CLEARCONSENT_DEV_PRO` can go away.
The license wrapper (`class-clearconsent-license.php`) is already written to read Freemius via a global
**`cc_fs()`** — `premium_enabled()`, `is_agency_license()`, and `state()` all consume it — so most of
the code side is "make `cc_fs()` exist and name the plans right," not new logic.

## ⚠️ Catch this before you create plans (tier-leakage)

`is_agency_license()` (license.php:72-73) returns true for `is_plan('agency')` **or
`is_plan('professional')`**. So if you name the **Pro** plan "professional," Pro customers would get the
**Agency** features (white-label + multisite push) at the Pro price. Two safe options:
- Name the paid plans **`pro`** and **`agency`** (avoid `professional` entirely), **and/or**
- Drop the stray `professional` check from line 73 so only `agency` grants agency features
  (recommended regardless — it removes the foot-gun no matter how plans get named later).

## Part A — In the Freemius dashboard (Jess)

1. Create a Freemius account; add a new **Plugin**. Set the slug to **`clearconsent`** to match the
   WordPress.org slug.
2. Create plans:
   - **Free** (default).
   - **Pro** — paid; slug **`pro`**. Unlocks scanning, automatic (buffer) blocking, unlimited
     services, Script Manager, custom styling, consent logging, translations.
   - **Agency** — paid; slug **`agency`**. Everything in Pro plus white-label and multisite push.
   - Do **not** create a plan named `professional` (see the catch above).
3. Set pricing (monthly/annual), any trial, and the per-plan feature lists (for the checkout page).
4. Copy the **Plugin ID** and **Public Key** (and the Secret Key for deployment).
5. Set the opt-in to **non-forced / skippable** — required for WordPress.org (usage tracking must be
   opt-in, and the plugin must not contact external servers before the user opts in).

## Part B — Code integration (Cursor build spec)

1. Bundle the Freemius WordPress SDK (`freemius/` folder) in the plugin.
2. Add the Freemius bootstrap near the top of `clearconsent.php` (must init early), defining the global
   **`cc_fs()`** — this is the function the license wrapper already calls. Standard pattern:
   `cc_fs()` lazy-inits with `fs_dynamic_init([...])` using the Plugin ID + Public Key, then
   `cc_fs()->set_basename( true, __FILE__ )`. Config: `has_premium_version => true`,
   `has_paid_plans => true`, `has_addons => false`, `menu => [ 'slug' => <ClearConsent settings page> ]`,
   `is_org_compliant => true` (opt-in). No other wiring needed — the wrapper consumes
   `is_registered` / `can_use_premium_code` / `is_paying` / `is_plan` / `get_plan_name` already.
3. Apply the tier-leakage fix from the top (drop the `professional` match), so the Pro/Agency boundary
   is unambiguous.
4. **Decision — free/premium code distribution** (pick one; affects launch effort):
   - **Runtime gating (recommended for launch).** Keep the single codebase; `premium_enabled()`
     disables Pro features for free users. The Pro PHP ships disabled in the .org download. Fastest,
     matches the current architecture; protection is the license/update entitlement, not code secrecy
     (and the code is GPL regardless).
   - **Freemius premium-code separation.** Mark Pro-only code with Freemius's `__premium_only`
     conventions so the free .org build is stripped of Pro code. More work; only worth it if keeping
     Pro code out of the *free download* matters to you. Can be done as a later pass.
5. Replace `CLEARCONSENT_DEV_PRO` as the source of truth. The `defined()` checks can stay as a
   dev-only escape hatch (harmless if never defined), but once `cc_fs()` is live, real license state
   drives everything — remove the `define()` from any wp-config (including staging, eventually).

## Part C — Testing (Claude Code, Freemius sandbox/test mode)

1. **Free** (not paying / opt-in skipped): banner + Layer-1 blocking work (via the local
   `clearconsent_ever_setup` flag — confirm protection runs even without a Freemius opt-in); 3-service
   cap enforced; scanning, buffer blocking, Script Manager, styling, logging, translations all locked.
2. **Pro** license: those unlock — **but white-label and multisite push stay locked.** Test this
   boundary explicitly; it's where the `professional` leak would show if the fix wasn't applied.
3. **Agency** license: white-label + multisite push unlock.
4. License lifecycle → `state()`: active (paying) → grace (premium code, not paying) → expired
   (was paying, lapsed) → confirm expired makes settings read-only (`config_editable()` false) while
   the banner/blocking keep running (lenient `protection_enabled()` gate).
5. Opt-in screen appears, is skippable, and nothing calls out before opt-in (the .org requirement).

## Sequencing vs the .org slug

The slug claim reviews the **free** plugin, so it doesn't have to wait on Freemius — you can submit the
free readme/plugin to start the 2–4 week clock and wire Freemius in parallel. Freemius (opt-in) is
allowed on .org, so it can ship in the first public version or as a fast follow. The slug clock is the
long pole; don't let Freemius block starting it.
