@funnelsgrove/cli 0.1.14 → 0.1.18

package/template_scaffold/AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+This file is generated from the FunnelsGrove step contract. Start at [the agent documentation router](docs/funnelsgrove/START-HERE.md), then read the exact page for the step type you are changing.
+
+## Route by task
+
+| Task | Read first |
+| --- | --- |
+| Add a step | [Add a step](docs/funnelsgrove/recipes/add-step.md) |
+| Edit a step | [Edit a step](docs/funnelsgrove/recipes/edit-step.md) |
+| Change metadata or routing | [Step metadata](docs/funnelsgrove/contracts/step-metadata.md) and [flow routing](docs/funnelsgrove/contracts/flow-routing.md) |
+| Add or edit choices | [Content and answers](docs/funnelsgrove/contracts/content-answers.md) |
+| Edit product strategy, plan, or copy | [Content and answers](docs/funnelsgrove/contracts/content-answers.md) |
+| Add an experiment | [Add an experiment](docs/funnelsgrove/recipes/add-experiment.md) |
+| Edit email capture or analytics | [Analytics events](docs/funnelsgrove/contracts/analytics-events.md) |
+| Edit paywall, checkout, or subscription flow | [Payments](docs/funnelsgrove/contracts/payments.md) |
+| Edit theme, CSS, layout, or images | [Start here](docs/funnelsgrove/START-HERE.md), [flow routing](docs/funnelsgrove/contracts/flow-routing.md), and [local QA](docs/funnelsgrove/qa/local.md) |
+| QA or publish | [Local QA](docs/funnelsgrove/qa/local.md), [analytics QA](docs/funnelsgrove/qa/analytics.md), and [publish QA](docs/funnelsgrove/qa/publish.md) |
+
+## Non-negotiable workflow
+
+1. Read the matching [step-type page](docs/funnelsgrove/steps/INDEX.md).
+2. Keep manifest metadata and component metadata identical.
+3. Use shared helpers for answers, conversions, checkout, handoff, and routing.
+4. Run `fgrove validate` and the relevant manual QA checklist.
+5. Publish preview first. Publish production only after explicit approval.
+
+## Sync safety
+
+1. Before edits run `fgrove status`, `git status --short`, and `fgrove github status` when the funnel is GitHub-connected.
+2. Never run `fgrove sync down` over changed synced source. Use `--force` only to intentionally discard those local changes.
+3. Sync-up uses remote compare-and-swap through the base draft version. On stale-draft rejection, download into a clean temporary directory, merge deliberately, rerun checks, and retry.
+4. GitHub-connected changes use git push, `fgrove github pull`, terminal status, then publish; never use `fgrove sync up` for the same diff. Non-GitHub funnels use `fgrove sync up`.
+5. Use `fgrove env pull` when only the ignored `.env` must be refreshed. Environment files never belong in synced source.
+
+Contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+## Project-specific context
+
+If an unmanaged `AGENTS.project.md` exists, read and apply `AGENTS.project.md` after this managed contract. It may add product-specific constraints, but if it conflicts with this bundle, the managed contract wins. The docs generator never creates, hashes, copies, overwrites, or deletes that file.

package/template_scaffold/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template_scaffold/PLAN.md

@@ -0,0 +1,81 @@
+# Funnel Implementation Plan
+
+## Plan Refinement Log
+- Pass 1: Define target audience, value promise, and baseline step sequence.
+- Pass 2: Refine copy hierarchy, CTA ownership, and branch behavior.
+- Pass 3: Validate paywall trust signals, routing, and mobile UX constraints.
+
+## Step Sequence
+Use runtime IDs in order. Keep names human-readable.
+
+### Step 1: step-1 - Opening
+**Goal:** Define first-screen value promise.
+**Headline:** _TBD_
+**Body:** _TBD_
+**CTA:** Continue
+**Interaction:** _TBD_
+**Image:** _none | generate | provided_
+
+### Step 2: step-2 - Qualification
+**Goal:** Collect key user context for personalization.
+**Headline:** _TBD_
+**Body:** _TBD_
+**CTA:** Continue
+**Interaction:** _TBD_
+**Image:** _none | generate | provided_
+
+### Step 3: step-3 - Processing / Insight
+**Goal:** Reinforce progress and maintain momentum.
+**Headline:** _TBD_
+**Body:** _TBD_
+**CTA:** Continue or auto-advance
+**Interaction:** _TBD_
+**Image:** _none | generate | provided_
+
+### Step 4: step-4 - Transformation
+**Goal:** Show outcome and prepare for conversion.
+**Headline:** _TBD_
+**Body:** _TBD_
+**CTA:** Continue
+**Interaction:** _TBD_
+**Image:** _none | generate | provided_
+
+### Step N: paywall - Offer
+**Goal:** Convert with clear value, pricing, and trust cues.
+**Headline:** _TBD_
+**Body:** _TBD_
+**CTA:** _TBD_
+**Interaction:** Select plan then purchase.
+**Image:** _optional_
+
+### Step N+1: subscription-started - Handoff
+**Goal:** Confirm purchase and route user to app/home experience.
+**Headline:** _TBD_
+**Body:** _TBD_
+**CTA:** _TBD_
+**Interaction:** Open app / deep link.
+
+## Funnel Fuel
+| Screen | Section / role | Feeling | Fuel |
+| --- | --- | --- | --- |
+
+## Paywall Requirements
+- Keep the live `paywall` aligned with ClaimBee Figma node `6992:6210`.
+- Preserve the prior implementation as the direct `/paywall-old` route for regression checks.
+- Keep visible `Money-back guarantee` copy.
+- Keep guarantee badge image: `/paywall/money-back-badge.png`.
+- Keep pricing/trial copy explicit and easy to scan.
+- Launch Stripe checkout in a dedicated modal dialog that matches the published checkout design.
+- In the modal, prioritize Stripe Link and express wallet buttons before the manual card form.
+- After a successful payment, redirect to `subscription-started` so the app handoff screen appears immediately.
+
+## CTA Ownership Rules
+- `FunnelFlow` owns default Continue action bar.
+- If `actionBar.hidden !== true`, do not render a duplicate local primary CTA.
+- For yes/no branches, define targets in routing config and use shared in-step controls.
+
+## Validation Checklist
+- Step IDs are stable (`step-*`, `paywall`, `subscription-started`).
+- Routing covers each active step and avoids dead ends.
+- Paywall trust elements are present.
+- Mobile layout remains full-screen with safe-area spacing.

package/template_scaffold/PRODUCT_SENSE.md

@@ -0,0 +1,28 @@
+# Product Sense
+
+## Product Summary
+Describe what the product does in one to two sentences.
+
+## Target Audience
+Describe the intended user segment, device assumptions, and market.
+
+## Traffic Promise
+Describe the ad/landing promise users arrive with.
+
+## Core Value Proposition
+Describe the main value delivered in the first user session.
+
+## Pricing Model
+Describe trial and paid plan structure (for example monthly/yearly).
+
+## Tone and Brand Voice
+Describe tone, style, and visual direction constraints.
+
+## Known Objections
+- List top objections.
+- List trust requirements.
+- List legal/compliance constraints if relevant.
+
+## Strategic Pre-Work
+| Problem | Why current solutions fail | Barrier | Value | Higher-level value |
+| --- | --- | --- | --- | --- |

package/template_scaffold/context/build-context.md

@@ -0,0 +1,34 @@
+# Build Context
+
+## Run Intent
+- Current intent: build
+- `plan`: update `PRODUCT_SENSE.md`, `PLAN.md`, and planning docs only.
+- `build`: implement runtime files under `src/` and assets under `public/`.
+
+## Project Structure
+- `src/app`: Next.js routes and shell pages.
+- `src/components`: flow shell and editor panel UI.
+- `src/config`: manifest, runtime metadata, and per-step billing config.
+- `src/runtime`: manifest helpers, flow controller, and step registry.
+- `src/steps`: step components and registry.
+- shared packages: `@funnelsgrove/runtime`, `@funnelsgrove/analytics`, `@funnelsgrove/payments`.
+
+## Source Of Truth Files (Build)
+- `src/config/funnel.manifest.ts` (flow, optional legacy entry points, branches, experiments, architecture version)
+- `src/runtime/step-registry.ts` (component ownership)
+- `src/steps/index.ts` (derived active step registry)
+- `src/runtime/use-funnel-flow-controller.ts` (flow orchestration, tracking, and runtime mode)
+- `src/components/FunnelFlow.tsx` (shell render)
+- `src/components/FunnelEditorPanel.tsx` (editor controls)
+- `docs/references/funnel-sdk-user-answers.md` (typed user answers + analytics usage)
+
+## Onboarding Artifacts
+- `PRODUCT_SENSE.md`: required
+- `PLAN.md`: required
+
+## Sequence Contract
+- Keep foundation anchors first: `step-1`, `step-2`, `step-3`, `step-4`
+- Keep conversion path terminal steps: `paywall`, `subscription-started`
+
+## Generation Mode
+- `baseline_five_step` by default unless a wider flow is explicitly requested.

package/template_scaffold/docs/AGENT_FUNNEL_IMPLEMENTATION_SPEC.md

@@ -0,0 +1,5 @@
+# Compatibility: agent funnel implementation spec
+
+The canonical agent contract moved to [FunnelsGrove start here](funnelsgrove/START-HERE.md).
+
+This compatibility page intentionally contains no copied taxonomy or workflow rules. Update the canonical bundle instead.

package/template_scaffold/docs/ARCHITECTURE.md

@@ -0,0 +1,5 @@
+# Compatibility: funnel architecture
+
+Use the canonical [step metadata contract](funnelsgrove/contracts/step-metadata.md) for step structure and [flow routing contract](funnelsgrove/contracts/flow-routing.md) for graph behavior.
+
+This compatibility page intentionally contains no normative contract copy.

package/template_scaffold/docs/FLOW_CONFIG_AND_ROUTING.md

@@ -0,0 +1,5 @@
+# Compatibility: flow configuration and routing
+
+Use the canonical [flow routing contract](funnelsgrove/contracts/flow-routing.md).
+
+This compatibility page intentionally contains no copied routing rules.

package/template_scaffold/docs/PAYWALL_AND_PAYMENTS.md

@@ -0,0 +1,5 @@
+# Compatibility: paywall and payments
+
+Use the canonical [payments contract](funnelsgrove/contracts/payments.md).
+
+This compatibility page intentionally contains no copied paywall taxonomy or provider rules.

package/template_scaffold/docs/README.md

@@ -0,0 +1,5 @@
+# Compatibility: funnel template documentation
+
+Start with the canonical [FunnelsGrove agent contract](funnelsgrove/START-HERE.md).
+
+The canonical router links step types, recipes, QA, analytics, routing, answers, payments, and migration guidance.

package/template_scaffold/docs/funnelsgrove/START-HERE.md

@@ -0,0 +1,73 @@
+# FunnelsGrove agent contract: start here
+
+This bundle is the operating manual for agents that create or edit a synced funnel. It is generated and validated against the runtime step contract; follow it before changing funnel code.
+
+<!-- funnelsgrove:generated:start contract-v3/overview/start-here -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Type | Family | Action owner | Required kind | Terminal | Meaning |
+| --- | --- | --- | --- | --- | --- |
+| `cancellation_offer` | `commerce` | `step` | `cancellation` | `false` | A cancellation retention or downsell surface. |
+| `checkout` | `commerce` | `step` | — | `false` | A dedicated payment-entry screen. |
+| `form_input` | `form` | `either` | — | `false` | Non-choice structured input, including reserved email capture. |
+| `intro_hero` | `content` | `shared-shell` | — | `false` | Opening promise or low-friction entry screen. |
+| `multi_select_choice` | `choice` | `either` | — | `false` | Multiple options are selected before explicit completion. |
+| `paywall_offer` | `commerce` | `step` | `paywall` | `false` | A monetization offer that presents purchasable plans. |
+| `progress_interstitial` | `transition` | `either` | — | `false` | Progress, calculation, loading, reveal, or transition screen. |
+| `purchase_completed` | `terminal` | `step` | `subscription-handoff` | `true` | The canonical terminal shown after a verified initial purchase. |
+| `single_step_choice` | `choice` | `step` | — | `false` | Exactly one standard option is selected. |
+| `single_step_choice_emoji` | `choice` | `step` | — | `false` | Exactly one emoji-led option is selected. |
+| `social_proof` | `content` | `shared-shell` | — | `false` | Testimonials, reviews, credibility, or evidence. |
+| `subscription_handoff` | `commerce` | `step` | `subscription-handoff` | `false` | A non-terminal app, store, or deep-link handoff. |
+| `subscription_management` | `commerce` | `step` | `manage-subscription` | `false` | A screen for managing or inspecting an existing subscription. |
+| `summary_confirmation` | `content` | `either` | — | `false` | A summary, review, or confirmation before the next action. |
+| `upsell_offer` | `commerce` | `step` | `upsell` | `false` | A post-purchase or upgrade offer. |
+| `value_prop_story` | `content` | `shared-shell` | — | `false` | Benefit, explanation, motivation, or narrative value screen. |
+
+### Reserved identities
+
+| Contract | Match | ID | Name | Type | Kind | Primary | Unique |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `email-capture` | `exact` | `email-capture` | `email-capture` | `form_input` | — | — | `true` |
+| `manage-subscription` | `exact` | `manage-subscription` | `manage-subscription` | `subscription_management` | `manage-subscription` | — | `true` |
+| `paywall` | `exact` | `paywall` | `paywall` | `paywall_offer` | `paywall` | `true` | `true` |
+| `paywall-variant` | `pattern` | `^paywall-[a-z0-9-]+$` | `^paywall-[a-z0-9-]+$` | `paywall_offer` | `paywall` | `false` | `false` |
+| `subscription-started` | `exact` | `subscription-started` | `subscription-started` | `purchase_completed` | `subscription-handoff` | — | `true` |
+<!-- funnelsgrove:generated:end contract-v3/overview/start-here -->
+
+## Choose the right document
+
+- Step classification and parity: [step metadata](contracts/step-metadata.md) and the [step-type index](steps/INDEX.md).
+- Analytics ownership and lifecycle: [analytics events](contracts/analytics-events.md).
+- Manifest edges, reserved routes, branches, and experiments: [flow routing](contracts/flow-routing.md).
+- Choice answers and email input: [content and answers](contracts/content-answers.md).
+- Paywall, checkout, and subscription behavior: [payments](contracts/payments.md).
+- New work: [add a step](recipes/add-step.md), [edit a step](recipes/edit-step.md), or [add an experiment](recipes/add-experiment.md).
+- Verification: [local QA](qa/local.md), [analytics QA](qa/analytics.md), [paywall/checkout QA](qa/paywall-checkout.md), and [publish QA](qa/publish.md).
+- Existing funnels: [step-contract v3 migration](migrations/step-contract-v3.md).
+
+## Non-negotiable guardrails
+
+- Classify a step by what the user can do, not its position, copy, or visual treatment.
+- A paywall presents purchasable plans. A loading, reveal, or “ready” screen is an interstitial.
+- Every choice declares `choice.answerKey`, stores stable option IDs in the exact scalar/array shape, and uses `useStepChoices`.
+- Email capture uses `submitEmailCapture`; it never manually sends analytics or hard-codes paywall navigation.
+- `subscription-started` is the `purchase_completed` terminal. Browser terminal reach is not Quiz completed; only the trusted backend records `purchase_completed` after verifying an initial purchase.
+- Let the controller distinguish completion from exit and suppress provider delivery in preview.
+
+## Standard workflow
+
+1. Read the exact type page.
+2. Change the smallest set of component, content/editor, registry, and manifest files needed.
+3. Keep component and manifest metadata in parity.
+4. Run `fgrove validate` and focused tests.
+5. Perform the relevant manual QA.
+6. Publish preview, inspect it, then publish production only with explicit approval.
+
+## Theme and styling ownership
+
+`src/theme/theme.ts` is the brand-token source. Preserve the typed `FunnelTheme` and `themeCssVariables = createThemeCssVariables(theme)`. Apply theme values through the emitted CSS variables: `globals.css` owns global reset, fonts, and root behavior; shared styles own repeated patterns; step-local CSS owns only genuinely local layout. Do not duplicate brand constants in step components.
+
+Optional product-specific guidance belongs in `AGENTS.project.md`. That file is never managed by this bundle.

package/template_scaffold/docs/funnelsgrove/contracts/analytics-events.md

@@ -0,0 +1,59 @@
+# Analytics event ownership
+
+Analytics is divided between controller-owned lifecycle events, explicit shared helpers, transactional server conversions, and trusted server claims.
+
+<!-- funnelsgrove:generated:start contract-v3/contract/analytics-events -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Contract key | Public event | Raw event | Allowed step types | Allowed identities | Owner | Automatic | Dedupe | Required metadata |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `add_payment_info` | `add_payment_info` | `add_payment_info` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-helper` | `false` | `event-id` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType`, `eventId` |
+| `checkout_completed` | `checkout_completed` | `checkout_completed` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-helper` | `false` | `event-id` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType`, `eventId` |
+| `checkout_started` | `checkout_started` | `checkout_started` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-helper` | `false` | `event-id` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType`, `eventId` |
+| `email_captured` | `email_captured` | `email_captured` | `form_input` | `email-capture` | `transactional-server` | `false` | `logical-email-conversion` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType`, `projectId`, `funnelEndUserId`, `eventId` |
+| `first_step_clicked` | `first_step_clicked` | `first_step_clicked` | `any` | `any` | `controller` | `true` | `step-visit` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType` |
+| `first_step_viewed` | `first_step_viewed` | `first_step_viewed` | `any` | `any` | `controller` | `true` | `step-visit` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType` |
+| `funnel_completed` | `funnel_completed` | `funnel_completed` | `purchase_completed` | `any` | `terminal-helper` | `false` | `funnel-run` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType`, `eventId` |
+| `funnel_started` | `funnel_started` | `funnel_start` | `any` | `any` | `controller` | `true` | `funnel-run` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion` |
+| `purchase_completed` | `purchase_completed` | `purchase_completed` | _None_ | _None_ | `trusted-server` | `false` | `provider-payment` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `projectId`, `funnelEndUserId`, `eventId`, `providerPaymentId`, `purchaseKind` |
+| `registration_completed` | `registration_completed` | `registration_completed` | _None_ | _None_ | `trusted-server` | `false` | `subscription-claim` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `projectId`, `funnelEndUserId`, `eventId`, `subscriptionClaimId` |
+| `step_completed` | `step_completed` | `step_end` | `any` | `any` | `controller` | `true` | `step-visit` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType` |
+| `step_engaged` | `step_engaged` | `step_engaged` | `any` | `any` | `controller` | `false` | `step-visit` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType`, `durationMs` |
+| `step_exited` | `step_exited` | `step_exit` | `any` | `any` | `controller` | `true` | `step-visit` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType` |
+| `step_started` | `step_started` | `step_start` | `any` | `any` | `controller` | `true` | `step-visit` | `funnelId`, `funnelVersionId`, `environment`, `stepContractVersion`, `stepId`, `stepName`, `stepType` |
+
+The `purchase_completed` event is owned by `trusted-server` and is recorded only after the backend verifies a successful initial purchase. Entering the browser terminal or emitting `funnel_completed` does not create this business conversion. The separate `registration_completed` event remains owned by `trusted-server` for the later app-link claim. The `email_captured` event is owned by `transactional-server` and uses `logical-email-conversion` deduplication.
+<!-- funnelsgrove:generated:end contract-v3/contract/analytics-events -->
+
+## Ownership rules
+
+- The flow controller emits lifecycle events. Step components do not duplicate them.
+- `step_engaged` is non-automatic and absent by default; only an explicit, centralized, tested policy may emit it through the approved controller/helper boundary.
+- `submitEmailCapture` creates `email_captured` transactionally, then routes only after success.
+- Named payment helpers emit checkout semantic events at real payment boundaries.
+- The terminal helper owns funnel completion.
+- A trusted backend owns `purchase_completed` after verifying an initial subscription or one-time payment; browser code never emits it, and terminal reach does not count as Quiz completed.
+- A separate trusted server claim owns `registration_completed` when the purchased subscription is later linked in the app.
+- Provider adapters and the durable outbox own PostHog and server Meta delivery.
+
+## Privacy boundary
+
+- Never put raw email or other PII in analytics event metadata or logs.
+- Only the server delivery boundary may use raw email as Meta hashing input.
+- PostHog properties must remain non-PII.
+
+## Completion versus exit
+
+Completion means the step’s intended action succeeded and navigation was committed. Back, close, unload, replaced visits, and abandoned payment are exits. The controller deduplicates each visit outcome. Preview suppresses API/provider delivery.
+
+## Email capture sequence
+
+1. Call `submitEmailCapture` once for the in-flight submit.
+2. On API failure, do not mutate answer state, lifecycle, or route.
+3. On a newly created conversion, browser Pixel/Google may fan out with the server event ID.
+4. On a duplicate, skip browser fanout and continue safely.
+5. Never call `trackLead`, PostHog, Meta CAPI, or a provider from the email step.
+
+Use the [analytics QA checklist](../qa/analytics.md) for journey-level evidence.

package/template_scaffold/docs/funnelsgrove/contracts/content-answers.md

@@ -0,0 +1,44 @@
+# Content, choices, and persisted answers
+
+Content labels may change; analytics-safe option IDs and answer keys must remain stable.
+
+<!-- funnelsgrove:generated:start contract-v3/contract/content-answers -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Type | Cardinality | Presentation | Completion | allowEmpty config |
+| --- | --- | --- | --- | --- |
+| `multi_select_choice` | `many` | `standard` | `explicit` | `true` |
+| `single_step_choice` | `one` | `standard` | `selection` | `false` |
+| `single_step_choice_emoji` | `one` | `emoji` | `selection` | `false` |
+
+| Capability | Allowed types | Allowed identities | Required owner |
+| --- | --- | --- | --- |
+| `choice-write` | `single_step_choice`, `single_step_choice_emoji`, `multi_select_choice` | `any` | `useStepChoices` |
+| `email-capture` | `form_input` | `email-capture` | `submitEmailCapture` |
+<!-- funnelsgrove:generated:end contract-v3/contract/content-answers -->
+
+## Choice rules
+
+- Declare `choice.answerKey` in manifest and component metadata.
+- Use stable option IDs, never labels, array positions, or entire objects.
+- Persist a scalar ID for single-choice types and an ID array for multi-select.
+- Represent an allowed empty multi-select as `[]`.
+- Use `useStepChoices` for write, completion, and routing order.
+
+## Form and email rules
+
+Ordinary form inputs validate and persist through their owning runtime path. The reserved email form calls `submitEmailCapture`; it never sends analytics manually and never decides the next route.
+
+## Content/editor parity
+
+Keep builder-editable values in content definitions, expose matching editor sections, and register them once. Do not move stable IDs or answer keys into editable copy.
+
+## Product strategy and plan ownership
+
+- `PRODUCT_SENSE.md` owns audience, promise, positioning, objections, value stack, and brand direction. Preserve `## Strategic Pre-Work` and its exact five columns.
+- `PLAN.md` owns the ordered screen contract, exact screen structure and copy, shared design system/components, and `## Funnel Fuel`. Keep one row per planned screen.
+- Update the owning artifact in the same change. Never implement a step absent from `PLAN.md`.
+
+See the exact choice and form pages in the [step-type index](../steps/INDEX.md). Run `fgrove validate` and test reload persistence before completion.

package/template_scaffold/docs/funnelsgrove/contracts/flow-routing.md

@@ -0,0 +1,41 @@
+# Flow routing contract
+
+The manifest graph owns routes. Components request an outcome; they do not choose a hard-coded destination.
+
+<!-- funnelsgrove:generated:start contract-v3/contract/flow-routing -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Contract | Match | ID | Name | Type | Kind | Primary | Unique |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `email-capture` | `exact` | `email-capture` | `email-capture` | `form_input` | — | — | `true` |
+| `manage-subscription` | `exact` | `manage-subscription` | `manage-subscription` | `subscription_management` | `manage-subscription` | — | `true` |
+| `paywall` | `exact` | `paywall` | `paywall` | `paywall_offer` | `paywall` | `true` | `true` |
+| `paywall-variant` | `pattern` | `^paywall-[a-z0-9-]+$` | `^paywall-[a-z0-9-]+$` | `paywall_offer` | `paywall` | `false` | `false` |
+| `subscription-started` | `exact` | `subscription-started` | `subscription-started` | `purchase_completed` | `subscription-handoff` | — | `true` |
+
+The `hardcoded-navigation` capability is owned by `manifest-flow-controller`.
+<!-- funnelsgrove:generated:end contract-v3/contract/flow-routing -->
+
+## Rules
+
+- Give public paths meaningful product slugs.
+- Keep `edgesByStepId` sources and targets as explicit string literals.
+- Model conditional ownership in `branches`, including readable labels, tags, and owned step IDs.
+- Keep every experiment control and variant as a real step with normal outgoing edges.
+- Configure the email-to-offer edge in the manifest; the email component never names a paywall route.
+- Keep inactive variants unreachable from the default flow rather than deleting their identity.
+
+## Lifecycle-safe navigation
+
+Use the flow controller so answer writes, semantic conversions, completion, and route commits stay ordered. A stale visit must not complete or navigate after a newer visit takes ownership.
+
+For experiments, follow [the add-experiment recipe](../recipes/add-experiment.md). Run `fgrove validate` after any graph change.
+
+## Asset and preload metadata
+
+- Give each funnel-critical image a stable `funnelManifest.assets` entry and attach it through the owning step's `assetIds`; every ID must resolve.
+- `assetIds` is routing/preload metadata, not an optimization opt-in. Use framework `priority` only for current first-viewport images.
+- `preload: 'idle'` is effective only when a tested shell consumer exists. Warm likely next-step assets only, never the full funnel; do not claim preload behavior from metadata alone.
+- Publish optimization is separate: the image-variants stage creates AVIF/WebP sidecars while retaining the original raster fallback.

package/template_scaffold/docs/funnelsgrove/contracts/payments.md

@@ -0,0 +1,42 @@
+# Payments and subscription contract
+
+Commerce steps use shared plan, checkout, wallet, handoff, and subscription helpers. Components own presentation and user intent, not provider integration.
+
+<!-- funnelsgrove:generated:start contract-v3/contract/payments -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Type | Family | Action owner | Required kind | Terminal | Meaning |
+| --- | --- | --- | --- | --- | --- |
+| `cancellation_offer` | `commerce` | `step` | `cancellation` | `false` | A cancellation retention or downsell surface. |
+| `checkout` | `commerce` | `step` | — | `false` | A dedicated payment-entry screen. |
+| `paywall_offer` | `commerce` | `step` | `paywall` | `false` | A monetization offer that presents purchasable plans. |
+| `subscription_handoff` | `commerce` | `step` | `subscription-handoff` | `false` | A non-terminal app, store, or deep-link handoff. |
+| `subscription_management` | `commerce` | `step` | `manage-subscription` | `false` | A screen for managing or inspecting an existing subscription. |
+| `upsell_offer` | `commerce` | `step` | `upsell` | `false` | A post-purchase or upgrade offer. |
+
+| Capability | Allowed types | Allowed identities | Required owner |
+| --- | --- | --- | --- |
+| `checkout` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-payment-helpers` |
+| `subscription-handoff` | `subscription_handoff`, `purchase_completed` | `any` | `runtime-handoff-helper` |
+| `subscription-management` | `subscription_management`, `cancellation_offer` | `any` | `runtime-subscription-helpers` |
+<!-- funnelsgrove:generated:end contract-v3/contract/payments -->
+
+## Paywall definition
+
+A paywall presents purchasable plans. A reveal, loading state, calculation, or “your plan is ready” bridge is a progress interstitial even when it precedes a paywall.
+
+## Payment rules
+
+- Resolve plans, prices, discounts, currencies, provider IDs, and payment mode from shared configuration.
+- Use named checkout helpers at actual checkout-started, payment-info, and completed boundaries.
+- Reuse the same event ID when retrying the same logical conversion.
+- Keep secrets and trusted provider calls server-side.
+- Route post-purchase behavior through the manifest and runtime handoff helper.
+
+## Purchase completion separation
+
+The canonical `subscription-started` route keeps its stable identity but uses the `purchase_completed` terminal type in contract v3. It may emit lifecycle-only `funnel_completed`, but entering it never counts as Quiz completed. Only the trusted backend emits `purchase_completed` after verifying an initial subscription or one-time payment; renewals, pending payments, and browser checkout returns do not qualify. `registration_completed` remains the later app-link conversion.
+
+Before publishing, complete [paywall/checkout QA](../qa/paywall-checkout.md) and [publish QA](../qa/publish.md).

package/template_scaffold/docs/funnelsgrove/contracts/step-metadata.md

@@ -0,0 +1,57 @@
+# Step metadata contract
+
+Step metadata is an analytics and runtime API, not descriptive decoration. Choose the type from actual behavior and preserve stable identity.
+
+<!-- funnelsgrove:generated:start contract-v3/contract/step-metadata -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Type | Family | Action owner | Required kind | Terminal | Meaning |
+| --- | --- | --- | --- | --- | --- |
+| `cancellation_offer` | `commerce` | `step` | `cancellation` | `false` | A cancellation retention or downsell surface. |
+| `checkout` | `commerce` | `step` | — | `false` | A dedicated payment-entry screen. |
+| `form_input` | `form` | `either` | — | `false` | Non-choice structured input, including reserved email capture. |
+| `intro_hero` | `content` | `shared-shell` | — | `false` | Opening promise or low-friction entry screen. |
+| `multi_select_choice` | `choice` | `either` | — | `false` | Multiple options are selected before explicit completion. |
+| `paywall_offer` | `commerce` | `step` | `paywall` | `false` | A monetization offer that presents purchasable plans. |
+| `progress_interstitial` | `transition` | `either` | — | `false` | Progress, calculation, loading, reveal, or transition screen. |
+| `purchase_completed` | `terminal` | `step` | `subscription-handoff` | `true` | The canonical terminal shown after a verified initial purchase. |
+| `single_step_choice` | `choice` | `step` | — | `false` | Exactly one standard option is selected. |
+| `single_step_choice_emoji` | `choice` | `step` | — | `false` | Exactly one emoji-led option is selected. |
+| `social_proof` | `content` | `shared-shell` | — | `false` | Testimonials, reviews, credibility, or evidence. |
+| `subscription_handoff` | `commerce` | `step` | `subscription-handoff` | `false` | A non-terminal app, store, or deep-link handoff. |
+| `subscription_management` | `commerce` | `step` | `manage-subscription` | `false` | A screen for managing or inspecting an existing subscription. |
+| `summary_confirmation` | `content` | `either` | — | `false` | A summary, review, or confirmation before the next action. |
+| `upsell_offer` | `commerce` | `step` | `upsell` | `false` | A post-purchase or upgrade offer. |
+| `value_prop_story` | `content` | `shared-shell` | — | `false` | Benefit, explanation, motivation, or narrative value screen. |
+
+### Reserved identities
+
+| Contract | Match | ID | Name | Type | Kind | Primary | Unique |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `email-capture` | `exact` | `email-capture` | `email-capture` | `form_input` | — | — | `true` |
+| `manage-subscription` | `exact` | `manage-subscription` | `manage-subscription` | `subscription_management` | `manage-subscription` | — | `true` |
+| `paywall` | `exact` | `paywall` | `paywall` | `paywall_offer` | `paywall` | `true` | `true` |
+| `paywall-variant` | `pattern` | `^paywall-[a-z0-9-]+$` | `^paywall-[a-z0-9-]+$` | `paywall_offer` | `paywall` | `false` | `false` |
+| `subscription-started` | `exact` | `subscription-started` | `subscription-started` | `purchase_completed` | `subscription-handoff` | — | `true` |
+<!-- funnelsgrove:generated:end contract-v3/contract/step-metadata -->
+
+## Required parity
+
+For each step, the manifest and exported component metadata must agree on `id`, `name`, `type`, optional `kind`, and optional `choice`. Keep `path`, `filePath`, `componentKey`, and title in the manifest. IDs and names are durable analytics keys.
+
+## Classification method
+
+1. Identify the screen’s user interaction and business purpose.
+2. Open the matching [step-type page](../steps/INDEX.md).
+3. Copy the fixture structure, then adapt only product-specific IDs, paths, copy, and content.
+4. Run `fgrove validate` before preview.
+
+## Protected metadata
+
+Do not rename an existing step, answer key, reserved identity, or analytics meaning as cleanup. Treat such changes as migrations with compatibility and measurement review.
+
+## Completion check
+
+Validation passes, metadata parity has no diagnostics, every reserved identity is exact, and analytics receives stable type/name values.

package/template_scaffold/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -0,0 +1,39 @@
+# Migrate a funnel to step contract v3
+
+<!-- funnelsgrove:generated:start contract-v3/migration/step-contract-v3 -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`. Contract v2 remains readable with `complete_registration`; migration to v3 changes that terminal type to `purchase_completed`. New v3 instructions must not author `complete_registration`.
+
+| Contract | Match | ID | Name | Type | Kind | Primary | Unique |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `email-capture` | `exact` | `email-capture` | `email-capture` | `form_input` | — | — | `true` |
+| `manage-subscription` | `exact` | `manage-subscription` | `manage-subscription` | `subscription_management` | `manage-subscription` | — | `true` |
+| `paywall` | `exact` | `paywall` | `paywall` | `paywall_offer` | `paywall` | `true` | `true` |
+| `paywall-variant` | `pattern` | `^paywall-[a-z0-9-]+$` | `^paywall-[a-z0-9-]+$` | `paywall_offer` | `paywall` | `false` | `false` |
+| `subscription-started` | `exact` | `subscription-started` | `subscription-started` | `purchase_completed` | `subscription-handoff` | — | `true` |
+
+### Package release order
+
+Release `@funnelsgrove/runtime` `0.1.59` first, then `@funnelsgrove/analytics` `0.1.36`, then `@funnelsgrove/cli` `0.1.18`. Deploy the API and funnel template only after those registry versions are available. Publishing packages and deploying production remain separately approved operational actions.
+<!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
+
+## Version-last policy
+
+1. Inventory every step, component metadata export, manifest entry, answer key, route, branch, experiment, and custom analytics call.
+2. Reclassify by behavior using the [step-type index](../steps/INDEX.md).
+3. Restore exact reserved identities and manifest/component parity.
+4. Move choice writes, email capture, payment events, handoff, routing, and lifecycle work to approved shared owners.
+5. Add/update fixtures and focused tests.
+6. Run `fgrove validate` and all [local](../qa/local.md), [analytics](../qa/analytics.md), and payment QA that applies.
+7. Change `stepContractVersion` only after every earlier step passes.
+
+Do not use the version field to silence diagnostics. Preserve legacy stable IDs and answer keys unless a separately planned data/analytics migration owns the change.
+
+## v2 compatibility
+
+Contract v2 funnels remain readable with the `complete_registration` terminal type. The v2-to-v3 migration preserves the `subscription-started` identity, route, file, transitions, and all unrelated metadata while changing only the contract version and terminal type to `purchase_completed`. New v3 authoring must never generate `complete_registration`.
+
+The migration does not turn browser terminal reach into a trusted conversion. Only the backend emits the v3 `purchase_completed` analytics event after verifying a successful initial subscription or one-time payment. `registration_completed` remains the separate later app-link event.