@funnelsgrove/cli 0.1.14 → 0.1.18

package/template_docs/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.

package/template_docs/docs/funnelsgrove/qa/analytics.md

@@ -0,0 +1,43 @@
+# Analytics QA
+
+<!-- funnelsgrove:generated:start contract-v3/qa/analytics -->
+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` |
+<!-- funnelsgrove:generated:end contract-v3/qa/analytics -->
+
+## Journey assertions
+
+- Funnel start occurs once per run.
+- Each visit has one start and exactly one completion or exit.
+- First-step view/click dedupe correctly.
+- If an explicit qualified policy emits `step_engaged`, it includes `durationMs` and deduplicates per visit; no default engagement event is expected.
+- Choice steps save the exact stable ID shape before completion.
+- Email success creates one server conversion; duplicate capture skips browser fanout; failure changes no state/lifecycle/route.
+- Checkout helpers fire only at real boundaries with complete metadata and stable event IDs.
+- Quiz completed requires trusted-server `purchase_completed`, deduplicated by `provider-payment`; browser `funnel_completed` is lifecycle-only and never satisfies it.
+- `registration_completed` remains the separate later app-link claim.
+- Preview sends no API/provider analytics.
+- No component sends PostHog or server Meta directly.
+- 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.
+
+Inspect raw events and user state, not only dashboard totals. Finish by running `fgrove validate`.

package/template_docs/docs/funnelsgrove/qa/local.md

@@ -0,0 +1,42 @@
+# Local QA
+
+<!-- funnelsgrove:generated:start contract-v3/qa/local -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Capability | Allowed types | Allowed identities | Required owner |
+| --- | --- | --- | --- |
+| `browser-registration-completed` | _None_ | _None_ | `trusted-subscription-claim-server` |
+| `checkout` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-payment-helpers` |
+| `choice-write` | `single_step_choice`, `single_step_choice_emoji`, `multi_select_choice` | `any` | `useStepChoices` |
+| `email-capture` | `form_input` | `email-capture` | `submitEmailCapture` |
+| `hardcoded-navigation` | _None_ | _None_ | `manifest-flow-controller` |
+| `provider-direct-analytics` | _None_ | _None_ | `analytics-adapter-outbox` |
+| `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/qa/local -->
+
+## Automated gate
+
+```bash
+npm run test:run
+npm run lint
+fgrove validate
+```
+
+Run the repository’s focused tests first, then its full validation gate. Also run `npm run docs:funnel-agent:check` when editing this source bundle.
+
+## Manual gate
+
+- Test small 375×667, medium 393×852, large 402×874, and desktop-small 1280×800.
+- At every declared breakpoint, require no horizontal scrolling, clipping, or overlap. Hiding overflow does not pass when content is clipped.
+- Keep the choice/input primary CTA visible without scrolling and every interactive tap target at least 44×44 CSS px.
+- Check pointer, keyboard, focus, loading, error, retry, refresh, back, and exit.
+- Verify answer persistence and manifest routes.
+- Assert every `assetId` resolves. Inspect the network to prove only current and likely-next assets preload; metadata alone is not proof.
+- Confirm theme values come from `src/theme/theme.ts` through emitted CSS variables rather than duplicated step-local constants.
+- Verify preview suppresses remote API/provider delivery.
+- Inspect the console and network for errors or duplicate requests.
+
+Complete the type-specific checklist in the [step-type index](../steps/INDEX.md).

package/template_docs/docs/funnelsgrove/qa/paywall-checkout.md

@@ -0,0 +1,55 @@
+# Paywall and checkout QA
+
+<!-- funnelsgrove:generated:start contract-v3/qa/paywall-checkout -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `paywall_offer`
+- Family: `commerce`
+- Description: A monetization offer that presents purchasable plans.
+- Action owner: `step`
+- Analytics role: `paywall`
+- Terminal: `false`
+- Required kind: `paywall`
+- Allowed kinds: `paywall`
+- Allowed semantic events: `checkout_started`, `add_payment_info`, `checkout_completed`
+- Forbidden capabilities: `choice-write`, `email-capture`, `subscription-management`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+_Not a choice type._
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+- `checkout` must be owned by `named-payment-helpers`.
+
+#### Reserved identities
+
+- `paywall`: id=`paywall`, name=`paywall`; type=`paywall_offer`; kind=`paywall`; primary=`true`; unique=`true`
+- `paywall-variant`: idPattern=`^paywall-[a-z0-9-]+$`, namePattern=`^paywall-[a-z0-9-]+$`; type=`paywall_offer`; kind=`paywall`; primary=`false`; unique=`false`
+<!-- funnelsgrove:generated:end contract-v3/qa/paywall-checkout -->
+
+## Classification and metadata
+
+- Confirm only screens with purchasable plans are paywalls.
+- Confirm primary and variant identities, types, kinds, paths, and component parity.
+- Confirm no secrets or provider IDs appear in JSX/client configuration.
+
+## Purchase paths
+
+- Verify every plan, price, currency, discount, and eligibility rule.
+- Test card and every enabled wallet.
+- Test validation, decline, retry, cancel, double-submit, and provider delay.
+- Verify named checkout events, complete metadata, one event ID, and retry deduplication.
+- Verify success routing and the `purchase_completed` terminal handoff.
+
+Run `fgrove validate` after all checks.

package/template_docs/docs/funnelsgrove/qa/publish.md

@@ -0,0 +1,32 @@
+# Publish QA
+
+<!-- funnelsgrove:generated:start contract-v3/qa/publish -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Capability | Allowed types | Allowed identities | Required owner |
+| --- | --- | --- | --- |
+| `browser-registration-completed` | _None_ | _None_ | `trusted-subscription-claim-server` |
+| `checkout` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-payment-helpers` |
+| `choice-write` | `single_step_choice`, `single_step_choice_emoji`, `multi_select_choice` | `any` | `useStepChoices` |
+| `email-capture` | `form_input` | `email-capture` | `submitEmailCapture` |
+| `hardcoded-navigation` | _None_ | _None_ | `manifest-flow-controller` |
+| `provider-direct-analytics` | _None_ | _None_ | `analytics-adapter-outbox` |
+| `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/qa/publish -->
+
+## Preview gate
+
+1. Run `fgrove status`, `git status --short`, tests, lint, `fgrove validate`, and relevant local/analytics/payment QA.
+2. Choose exactly one source path. GitHub-connected funnels 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`.
+3. Publish preview with a clear message.
+4. Test the preview URL across supported breakpoints and real navigation entry points.
+5. Confirm preview-mode suppression and production configuration separation.
+6. Review route, analytics, answer, experiment, and payment evidence.
+7. Confirm the `imageVariants` stage completed, supported browsers receive AVIF/WebP, and the original raster remains the fallback.
+
+## Production gate
+
+Publish production only after explicit approval and successful preview QA. Confirm the selected project/funnel/environment immediately before publishing, then smoke-test the live journey without creating duplicate conversions.

package/template_docs/docs/funnelsgrove/recipes/add-experiment.md

@@ -0,0 +1,34 @@
+# Recipe: add an experiment
+
+<!-- funnelsgrove:generated:start contract-v3/recipe/add-experiment -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Capability | Allowed types | Allowed identities | Required owner |
+| --- | --- | --- | --- |
+| `browser-registration-completed` | _None_ | _None_ | `trusted-subscription-claim-server` |
+| `checkout` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-payment-helpers` |
+| `choice-write` | `single_step_choice`, `single_step_choice_emoji`, `multi_select_choice` | `any` | `useStepChoices` |
+| `email-capture` | `form_input` | `email-capture` | `submitEmailCapture` |
+| `hardcoded-navigation` | _None_ | _None_ | `manifest-flow-controller` |
+| `provider-direct-analytics` | _None_ | _None_ | `analytics-adapter-outbox` |
+| `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/recipe/add-experiment -->
+
+## Procedure
+
+1. Build and validate every control/variant step before activation.
+2. Give each variant a stable, contract-compliant identity and normal outgoing edge.
+3. Create the experiment through FunnelsGrove so the platform owns the database row, feature flag, and generated experiment snapshot.
+4. Keep variant keys, labels, traffic percentages, source step, and route targets aligned.
+5. Resolve assignment and any redirect before creating the destination step visit.
+6. Keep the default flow valid when the experiment is stopped or assignment is unavailable.
+7. Run experiment-focused tests, then `fgrove validate`.
+
+## Pre-activation QA
+
+Force every assignment, verify analytics metadata and deduplication, confirm refresh keeps assignment, test missing/invalid flags, and leave inactive variants unreachable from the default flow.
+
+Pre-activation, missing-assignment, invalid-assignment, and fallback paths must not create phantom `step_started`, `step_completed`, or `step_exited` events.

package/template_docs/docs/funnelsgrove/recipes/add-step.md

@@ -0,0 +1,33 @@
+# Recipe: add a step
+
+<!-- funnelsgrove:generated:start contract-v3/recipe/add-step -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Capability | Allowed types | Allowed identities | Required owner |
+| --- | --- | --- | --- |
+| `browser-registration-completed` | _None_ | _None_ | `trusted-subscription-claim-server` |
+| `checkout` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-payment-helpers` |
+| `choice-write` | `single_step_choice`, `single_step_choice_emoji`, `multi_select_choice` | `any` | `useStepChoices` |
+| `email-capture` | `form_input` | `email-capture` | `submitEmailCapture` |
+| `hardcoded-navigation` | _None_ | _None_ | `manifest-flow-controller` |
+| `provider-direct-analytics` | _None_ | _None_ | `analytics-adapter-outbox` |
+| `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/recipe/add-step -->
+
+## Procedure
+
+1. Choose the exact type from the [step-type index](../steps/INDEX.md).
+2. Add the component and exported metadata.
+3. Add matching manifest metadata, path, file path, and component key.
+4. Add the registry entry.
+5. Add content/editor definitions and registry entries only when builder-editable.
+6. Add manifest edges, branches, assets, and tests required by the behavior.
+7. Start from the type’s golden fixture and preserve answer/helper semantics.
+8. Run focused tests, then `fgrove validate`.
+
+## Manual QA
+
+Render at all default breakpoints; test keyboard/pointer interaction, refresh/back/exit, answer persistence, lifecycle events, and every outgoing route. The recipe is complete only when the matching QA checklist passes.

package/template_docs/docs/funnelsgrove/recipes/edit-step.md

@@ -0,0 +1,31 @@
+# Recipe: edit a step
+
+<!-- funnelsgrove:generated:start contract-v3/recipe/edit-step -->
+Step contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+
+| Capability | Allowed types | Allowed identities | Required owner |
+| --- | --- | --- | --- |
+| `browser-registration-completed` | _None_ | _None_ | `trusted-subscription-claim-server` |
+| `checkout` | `paywall_offer`, `upsell_offer`, `checkout` | `any` | `named-payment-helpers` |
+| `choice-write` | `single_step_choice`, `single_step_choice_emoji`, `multi_select_choice` | `any` | `useStepChoices` |
+| `email-capture` | `form_input` | `email-capture` | `submitEmailCapture` |
+| `hardcoded-navigation` | _None_ | _None_ | `manifest-flow-controller` |
+| `provider-direct-analytics` | _None_ | _None_ | `analytics-adapter-outbox` |
+| `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/recipe/edit-step -->
+
+## Procedure
+
+1. Read the current type page from the [step-type index](../steps/INDEX.md).
+2. Decide whether the requested behavior still matches the existing type.
+3. Preserve stable IDs, names, paths, answer keys, option IDs, and reserved identities unless the request is an explicit migration.
+4. Update component, content/editor, registry, manifest, and tests only where the change requires.
+5. Keep component and manifest metadata in parity.
+6. Run focused tests, then `fgrove validate`.
+
+## Manual QA
+
+Re-run the complete current interaction, not just the changed visual state. Confirm existing analytics keys, answer shapes, lifecycle outcome, and routes remain intact.

package/template_docs/docs/funnelsgrove/steps/INDEX.md

@@ -0,0 +1,26 @@
+# Step-type index
+
+Choose the page whose type describes the screen's actual behavior. Do not classify from its position or visual treatment.
+
+| Type | Family | Use |
+| --- | --- | --- |
+| [`cancellation_offer`](cancellation_offer.md) | `commerce` | A cancellation retention or downsell surface. |
+| [`checkout`](checkout.md) | `commerce` | A dedicated payment-entry screen. |
+| [`form_input`](form_input.md) | `form` | Non-choice structured input, including reserved email capture. |
+| [`intro_hero`](intro_hero.md) | `content` | Opening promise or low-friction entry screen. |
+| [`multi_select_choice`](multi_select_choice.md) | `choice` | Multiple options are selected before explicit completion. |
+| [`paywall_offer`](paywall_offer.md) | `commerce` | A monetization offer that presents purchasable plans. |
+| [`progress_interstitial`](progress_interstitial.md) | `transition` | Progress, calculation, loading, reveal, or transition screen. |
+| [`purchase_completed`](purchase_completed.md) | `terminal` | The canonical terminal shown after a verified initial purchase. |
+| [`single_step_choice`](single_step_choice.md) | `choice` | Exactly one standard option is selected. |
+| [`single_step_choice_emoji`](single_step_choice_emoji.md) | `choice` | Exactly one emoji-led option is selected. |
+| [`social_proof`](social_proof.md) | `content` | Testimonials, reviews, credibility, or evidence. |
+| [`subscription_handoff`](subscription_handoff.md) | `commerce` | A non-terminal app, store, or deep-link handoff. |
+| [`subscription_management`](subscription_management.md) | `commerce` | A screen for managing or inspecting an existing subscription. |
+| [`summary_confirmation`](summary_confirmation.md) | `content` | A summary, review, or confirmation before the next action. |
+| [`upsell_offer`](upsell_offer.md) | `commerce` | A post-purchase or upgrade offer. |
+| [`value_prop_story`](value_prop_story.md) | `content` | Benefit, explanation, motivation, or narrative value screen. |
+
+Contract version: `3`
+
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`

package/template_docs/docs/funnelsgrove/steps/cancellation_offer.md

@@ -0,0 +1,112 @@
+# `cancellation_offer`
+
+## Use when / do not use when
+
+Use for cancellation retention or a downsell. Do not use for subscription overview, acquisition paywall, or ordinary upsell.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/cancellation_offer -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `cancellation_offer`
+- Family: `commerce`
+- Description: A cancellation retention or downsell surface.
+- Action owner: `step`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: `cancellation`
+- Allowed kinds: `cancellation`
+- Allowed semantic events: _None_
+- Forbidden capabilities: `choice-write`, `email-capture`, `checkout`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+_Not a choice type._
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+- `subscription-management` must be owned by `runtime-subscription-helpers`.
+
+#### Reserved identities
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'save-offer',
+  name: 'save-offer',
+  path: '/save-offer',
+  filePath: 'src/steps/step-save-offer.tsx',
+  componentKey: 'stepSaveOffer',
+  type: 'cancellation_offer',
+  kind: 'cancellation',
+  title: 'Stay with us',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'save-offer',
+  name: 'save-offer',
+  type: 'cancellation_offer',
+  kind: 'cancellation',
+  figmaNodeId: 'golden:cancellation-offer',
+  title: 'Stay with us',
+  description: 'Offer a retention path before cancellation.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'cancellation_offer',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime subscription helpers',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/cancellation_offer -->
+
+## Interaction and persisted answer shape
+
+Use runtime subscription helpers for keep/cancel/offer actions. Do not persist provider state as a funnel answer.
+
+## Automatic lifecycle events
+
+The controller owns the step outcome; subscription APIs own cancellation state transitions.
+
+## Required semantic conversions
+
+None in the browser unless a separate server-owned event contract is added.
+
+## Approved shared helpers
+
+Use runtime subscription helpers and manifest routing.
+
+## MUST rules
+
+- Preserve the cancellation kind.
+- Make accept, decline, and final cancellation outcomes unambiguous.
+
+## NEVER rules
+
+- Never claim a save before server confirmation.
+- Never send provider analytics directly.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `cancellation_offer.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test keep, accept offer, continue cancellation, failures/retries, refreshed state, and every resulting route.

package/template_docs/docs/funnelsgrove/steps/checkout.md

@@ -0,0 +1,120 @@
+# `checkout`
+
+## Use when / do not use when
+
+Use for a dedicated payment-entry screen. Do not use for plan merchandising without payment entry or for subscription management.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/checkout -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `checkout`
+- Family: `commerce`
+- Description: A dedicated payment-entry screen.
+- Action owner: `step`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: _none_
+- Allowed kinds: _None_
+- Allowed semantic events: `checkout_started`, `add_payment_info`, `checkout_completed`
+- Forbidden capabilities: `choice-write`, `email-capture`, `subscription-management`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+_Not a choice type._
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+- `checkout` must be owned by `named-payment-helpers`.
+
+#### Reserved identities
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'checkout',
+  name: 'checkout',
+  path: '/checkout',
+  filePath: 'src/steps/step-checkout.tsx',
+  componentKey: 'stepCheckout',
+  type: 'checkout',
+  title: 'Secure checkout',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'checkout',
+  name: 'checkout',
+  type: 'checkout',
+  figmaNodeId: 'golden:checkout',
+  title: 'Secure checkout',
+  description: 'Collect payment through shared checkout UI.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'checkout',
+  manifestStep,
+  componentMeta,
+  requiredEventMetadata: [
+    'funnelId',
+    'funnelVersionId',
+    'environment',
+    'stepContractVersion',
+    'stepId',
+    'stepName',
+    'stepType',
+    'eventId',
+  ],
+  semanticHelpers: ['trackCheckoutStarted', 'trackPaymentInfoSubmitted', 'trackCheckoutCompleted'],
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/checkout -->
+
+## Interaction and persisted answer shape
+
+The payment package owns payment state. Do not persist card, wallet, price, or provider data as funnel answers.
+
+## Automatic lifecycle events
+
+The controller owns step lifecycle. Payment helpers own semantic conversion boundaries and event IDs.
+
+## Required semantic conversions
+
+Use the named checkout-started, payment-info, and checkout-completed helpers with the complete required metadata returned by runtime context.
+
+## Approved shared helpers
+
+Use `trackCheckoutStarted`, `trackPaymentInfoSubmitted`, `trackCheckoutCompleted`, and shared checkout UI/runtime helpers.
+
+## MUST rules
+
+- Keep secrets server-side and provider IDs in configuration.
+- Reuse one event ID per logical conversion and allow safe retries.
+
+## NEVER rules
+
+- Never capture raw payment details yourself.
+- Never send incomplete, fabricated, or direct-provider analytics.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `checkout.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test all payment methods, validation, decline, retry, success, deduplication, required metadata, and post-success routing.