@funnelsgrove/cli 0.1.14 → 0.1.18

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

@@ -0,0 +1,112 @@
+# `upsell_offer`
+
+## Use when / do not use when
+
+Use for a post-purchase or upgrade offer. Do not use for the primary plan-selection paywall or a non-purchasable value screen.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/upsell_offer -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `upsell_offer`
+- Family: `commerce`
+- Description: A post-purchase or upgrade offer.
+- Action owner: `step`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: `upsell`
+- Allowed kinds: `upsell`
+- 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: 'premium-upgrade',
+  name: 'premium-upgrade',
+  path: '/premium-upgrade',
+  filePath: 'src/steps/step-premium-upgrade.tsx',
+  componentKey: 'stepPremiumUpgrade',
+  type: 'upsell_offer',
+  kind: 'upsell',
+  title: 'Add premium support',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'premium-upgrade',
+  name: 'premium-upgrade',
+  type: 'upsell_offer',
+  kind: 'upsell',
+  figmaNodeId: 'golden:upsell-offer',
+  title: 'Add premium support',
+  description: 'Offer an optional post-purchase upgrade.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'upsell_offer',
+  manifestStep,
+  componentMeta,
+  semanticHelpers: ['trackCheckoutStarted', 'trackPaymentInfoSubmitted', 'trackCheckoutCompleted'],
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/upsell_offer -->
+
+## Interaction and persisted answer shape
+
+Resolve the upgrade through shared payment configuration. Accept and decline both flow through controller-owned routes.
+
+## Automatic lifecycle events
+
+The controller owns lifecycle completion/exit; the payment boundary owns semantic checkout events.
+
+## Required semantic conversions
+
+Call `trackCheckoutStarted`, `trackPaymentInfoSubmitted`, and `trackCheckoutCompleted` only at their matching real boundaries.
+
+## Approved shared helpers
+
+Use named payment helpers and manifest routing.
+
+## MUST rules
+
+- Keep offer identity and pricing configuration outside the component.
+- Make decline behavior explicit in the manifest.
+
+## NEVER rules
+
+- Never emit a completed checkout before provider success.
+- Never call provider analytics directly.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `upsell_offer.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test accept, decline, provider failure, retry, event deduplication, and both manifest routes.

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

@@ -0,0 +1,110 @@
+# `value_prop_story`
+
+## Use when / do not use when
+
+Use for benefit, explanation, motivation, or narrative value. Do not use for testimonials, answer collection, loading, or an offer.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/value_prop_story -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `value_prop_story`
+- Family: `content`
+- Description: Benefit, explanation, motivation, or narrative value screen.
+- Action owner: `shared-shell`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: _none_
+- Allowed kinds: _None_
+- Allowed semantic events: _None_
+- Forbidden capabilities: `choice-write`, `email-capture`, `checkout`, `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
+
+_No special capability is allowed._
+
+#### Reserved identities
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'your-plan',
+  name: 'your-plan',
+  path: '/your-plan',
+  filePath: 'src/steps/step-your-plan.tsx',
+  componentKey: 'stepYourPlan',
+  type: 'value_prop_story',
+  title: 'Your plan',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'your-plan',
+  name: 'your-plan',
+  type: 'value_prop_story',
+  figmaNodeId: 'golden:value-prop-story',
+  title: 'Your plan',
+  description: 'Narrative explanation of the product value.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'value_prop_story',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'shared-shell',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/value_prop_story -->
+
+## Interaction and persisted answer shape
+
+This is a content screen and normally persists no answer. The shared shell owns standard progression.
+
+## Automatic lifecycle events
+
+The flow controller owns lifecycle events and suppresses them in preview.
+
+## Required semantic conversions
+
+None.
+
+## Approved shared helpers
+
+Use shared content and action-bar primitives. Use manifest routing for progression.
+
+## MUST rules
+
+- Keep one clear narrative purpose.
+- Keep manifest and component metadata in parity.
+
+## NEVER rules
+
+- Never classify a reveal or calculation screen as a value story.
+- Never send provider analytics directly.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `value_prop_story.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm content renders at all supported breakpoints and the shared action advances to the manifest-resolved target.

package/template_docs/funnel-docs.config.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": 1,
+  "bundleVersion": "2.0.6",
+  "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
+  "fullyGenerated": [
+    ".funnelsgrove-docs.json",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "docs/funnelsgrove/steps/INDEX.md"
+  ],
+  "curated": [
+    { "path": "docs/funnelsgrove/START-HERE.md", "logicalId": "overview/start-here" },
+    { "path": "docs/funnelsgrove/contracts/analytics-events.md", "logicalId": "contract/analytics-events" },
+    { "path": "docs/funnelsgrove/contracts/content-answers.md", "logicalId": "contract/content-answers" },
+    { "path": "docs/funnelsgrove/contracts/flow-routing.md", "logicalId": "contract/flow-routing" },
+    { "path": "docs/funnelsgrove/contracts/payments.md", "logicalId": "contract/payments" },
+    { "path": "docs/funnelsgrove/contracts/step-metadata.md", "logicalId": "contract/step-metadata" },
+    { "path": "docs/funnelsgrove/migrations/step-contract-v3.md", "logicalId": "migration/step-contract-v3" },
+    { "path": "docs/funnelsgrove/qa/analytics.md", "logicalId": "qa/analytics" },
+    { "path": "docs/funnelsgrove/qa/local.md", "logicalId": "qa/local" },
+    { "path": "docs/funnelsgrove/qa/paywall-checkout.md", "logicalId": "qa/paywall-checkout" },
+    { "path": "docs/funnelsgrove/qa/publish.md", "logicalId": "qa/publish" },
+    { "path": "docs/funnelsgrove/recipes/add-experiment.md", "logicalId": "recipe/add-experiment" },
+    { "path": "docs/funnelsgrove/recipes/add-step.md", "logicalId": "recipe/add-step" },
+    { "path": "docs/funnelsgrove/recipes/edit-step.md", "logicalId": "recipe/edit-step" },
+    { "path": "docs/funnelsgrove/steps/cancellation_offer.md", "logicalId": "step/cancellation_offer" },
+    { "path": "docs/funnelsgrove/steps/checkout.md", "logicalId": "step/checkout" },
+    { "path": "docs/funnelsgrove/steps/form_input.md", "logicalId": "step/form_input" },
+    { "path": "docs/funnelsgrove/steps/intro_hero.md", "logicalId": "step/intro_hero" },
+    { "path": "docs/funnelsgrove/steps/multi_select_choice.md", "logicalId": "step/multi_select_choice" },
+    { "path": "docs/funnelsgrove/steps/paywall_offer.md", "logicalId": "step/paywall_offer" },
+    { "path": "docs/funnelsgrove/steps/progress_interstitial.md", "logicalId": "step/progress_interstitial" },
+    { "path": "docs/funnelsgrove/steps/purchase_completed.md", "logicalId": "step/purchase_completed" },
+    { "path": "docs/funnelsgrove/steps/single_step_choice.md", "logicalId": "step/single_step_choice" },
+    { "path": "docs/funnelsgrove/steps/single_step_choice_emoji.md", "logicalId": "step/single_step_choice_emoji" },
+    { "path": "docs/funnelsgrove/steps/social_proof.md", "logicalId": "step/social_proof" },
+    { "path": "docs/funnelsgrove/steps/subscription_handoff.md", "logicalId": "step/subscription_handoff" },
+    { "path": "docs/funnelsgrove/steps/subscription_management.md", "logicalId": "step/subscription_management" },
+    { "path": "docs/funnelsgrove/steps/summary_confirmation.md", "logicalId": "step/summary_confirmation" },
+    { "path": "docs/funnelsgrove/steps/upsell_offer.md", "logicalId": "step/upsell_offer" },
+    { "path": "docs/funnelsgrove/steps/value_prop_story.md", "logicalId": "step/value_prop_story" }
+  ]
+}

package/template_scaffold/.env.example

@@ -0,0 +1,41 @@
+APP_DEALS_API_BASE_URL=http://localhost:4001
+NEXT_PUBLIC_APP_DEALS_API_BASE_URL=http://localhost:4001
+
+# SDK publishable key used by /api/sdk/session and /api/events
+FUNNEL_SDK_PUBLISHABLE_KEY=pk_test_app_deals_seed_public
+NEXT_PUBLIC_FUNNEL_SDK_PUBLISHABLE_KEY=pk_test_app_deals_seed_public
+
+# Optional when one SDK key can access multiple funnels
+FUNNEL_ID=
+NEXT_PUBLIC_FUNNEL_ID=
+NEXT_PUBLIC_PROJECT_ID=
+NEXT_PUBLIC_POSTHOG_PROJECT_API_KEY=
+NEXT_PUBLIC_FUNNEL_FAVICON_URL=
+NEXT_PUBLIC_FUNNEL_PAGE_TITLE=
+NEXT_PUBLIC_FUNNEL_PAGE_DESCRIPTION=
+NEXT_PUBLIC_FUNNEL_PAGE_PREVIEW_IMAGE_URL=
+NEXT_PUBLIC_FUNNEL_COMPANY_NAME=
+NEXT_PUBLIC_FUNNEL_COMPANY_ADDRESS=
+NEXT_PUBLIC_FUNNEL_COMPANY_COUNTRY=
+NEXT_PUBLIC_FUNNEL_PRIVACY_URL=
+NEXT_PUBLIC_FUNNEL_TERMS_URL=
+NEXT_PUBLIC_FUNNEL_SUPPORT_EMAIL=
+
+# Secret key used by /api/subscription (server-side only)
+FUNNEL_SDK_SECRET_KEY=
+
+# Existing Stripe payment intent server config (paywall checkout)
+STRIPE_ACTIVE_MODE=test
+STRIPE_TEST_SECRET_KEY=
+STRIPE_LIVE_SECRET_KEY=
+NEXT_PUBLIC_STRIPE_ACTIVE_MODE=test
+NEXT_PUBLIC_STRIPE_TEST_PUBLISHABLE_KEY=
+NEXT_PUBLIC_STRIPE_LIVE_PUBLISHABLE_KEY=
+
+# Post-checkout mobile handoff (step: /subscription-started)
+NEXT_PUBLIC_IOS_APP_STORE_URL=
+NEXT_PUBLIC_ANDROID_PLAY_STORE_URL=
+NEXT_PUBLIC_FUNNEL_UNIVERSAL_LINK=
+NEXT_PUBLIC_FUNNEL_IOS_DEEP_LINK=
+NEXT_PUBLIC_FUNNEL_ANDROID_DEEP_LINK=
+NEXT_PUBLIC_FUNNEL_QR_TARGET=

package/template_scaffold/.funnelsgrove-contract-tools.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "stepContractVersion": 3,
+  "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
+  "managedFiles": [
+    {
+      "path": "src/contract/funnel-project.validation.ts",
+      "sha256": "b0ec02eac1bd56812eef773be71628ae4e94f80fcd88837bbc5c8bf04e73a62c"
+    },
+    {
+      "path": "src/contract/funnel-validator.vite.config.ts",
+      "sha256": "014c0c2c5e29d98e7c91548f233843d83630905ba20c10d248364271ca448e9b"
+    },
+    {
+      "path": "src/contract/validate-funnel.cli.ts",
+      "sha256": "1b268b194865d633c760b704a0d4552adc2eb4526801da138ab2a4036f643d58"
+    }
+  ]
+}

package/template_scaffold/.funnelsgrove-docs.json

@@ -0,0 +1,144 @@
+{
+  "schemaVersion": 1,
+  "bundleVersion": "2.0.6",
+  "stepContractVersion": 3,
+  "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
+  "managedFiles": [
+    {
+      "path": "AGENTS.md",
+      "sha256": "952fbafb5841b8f2e6fadab5032374c98390ef90c1ca0ed27747a38d0cc009d7"
+    },
+    {
+      "path": "CLAUDE.md",
+      "sha256": "336cc4fbf19beaada7ccf9986414fa91851a8d7a07dfb3ccbe800a69eed0ab49"
+    },
+    {
+      "path": "docs/funnelsgrove/START-HERE.md",
+      "sha256": "638615b66f771a36015d747fd8e8a1bf0af311ed24631c3dd041388e8e73c09d"
+    },
+    {
+      "path": "docs/funnelsgrove/contracts/analytics-events.md",
+      "sha256": "743ca0d6b3a19b3b9e0bd489b228dab7be73d26073a86aab513a90477da481c6"
+    },
+    {
+      "path": "docs/funnelsgrove/contracts/content-answers.md",
+      "sha256": "403b286060dd6cda33757df7c55c5b0e17395f2d90aad0fc133d6ba1919a04b3"
+    },
+    {
+      "path": "docs/funnelsgrove/contracts/flow-routing.md",
+      "sha256": "050564846bf7d44afb267e1321d6fe277f032fe7b6237441741570c723543d0e"
+    },
+    {
+      "path": "docs/funnelsgrove/contracts/payments.md",
+      "sha256": "1a003f83fa01dba60bd4bb3365fd0a753dadd73d13fed84fd16b70d1df3d2b60"
+    },
+    {
+      "path": "docs/funnelsgrove/contracts/step-metadata.md",
+      "sha256": "de89a1a672abbe82d0e9c44da536d2a00893bf85fdec225b3aff7ecd7a965f20"
+    },
+    {
+      "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
+      "sha256": "ea1f65198292bfbb2f018fd39f583dfa5c6e1760b77612d804c91d59029ac98d"
+    },
+    {
+      "path": "docs/funnelsgrove/qa/analytics.md",
+      "sha256": "5ac36e547155546be230b9f1df144c7875824686627859c97b43e33d6e3e116d"
+    },
+    {
+      "path": "docs/funnelsgrove/qa/local.md",
+      "sha256": "97da7e26c5dbe8f63e654e4e0a035a4ecfbb9bcfd80db67d45c627141d6a2756"
+    },
+    {
+      "path": "docs/funnelsgrove/qa/paywall-checkout.md",
+      "sha256": "6fc887772e52ddd99ab70d898d8fd9b89869ca49ce1b49152d232cbe32865aae"
+    },
+    {
+      "path": "docs/funnelsgrove/qa/publish.md",
+      "sha256": "82b05b8c6eebf25d32d2cff6f05b08bc39661dcbb46caa6b912de6b803aed39c"
+    },
+    {
+      "path": "docs/funnelsgrove/recipes/add-experiment.md",
+      "sha256": "832b4331d6690d0596800c5aeb969f608dd62cf63d9ae527054e832fb60f8abd"
+    },
+    {
+      "path": "docs/funnelsgrove/recipes/add-step.md",
+      "sha256": "fba92b8394b0d622b9886a677af38ddb78042a633c60ab5cb6b1ff600abe2cb9"
+    },
+    {
+      "path": "docs/funnelsgrove/recipes/edit-step.md",
+      "sha256": "49eb688c0b3145c025dffe30a9be35e5f5e018da66cbeddf2a08af6a1cc250dc"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/INDEX.md",
+      "sha256": "86db94292eae2fffcd89795dedeab1eca32ce4d360d36f5d4b0806698642384f"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/cancellation_offer.md",
+      "sha256": "144e31d14c8a3cc832abcb5404f47da67308c412ec630f88b8ef54cb19a6f73a"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/checkout.md",
+      "sha256": "272ce5ae593bd8354e18f20a529daf39005226ca3f57b89db20095017d64c94f"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/form_input.md",
+      "sha256": "650a2d84cabf309f90fa7d37ac4101ea4002b2f2da4548ce80ed86f2194eba9e"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/intro_hero.md",
+      "sha256": "85de9bd3e4f7ec6af3dedb44340de4087939f679748cf796b9f5214936a8737b"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/multi_select_choice.md",
+      "sha256": "d9c6d7d75ccc6c50697033b3ad2a6383554d815d8f952c75f8319e73b09db1d1"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/paywall_offer.md",
+      "sha256": "969ee556ca1da3bfa09c21f530726467735693537452fcbf3065f21644b90669"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/progress_interstitial.md",
+      "sha256": "7ed2d0bf4ac45ee74e36bd87865c250206353ddbd6b34b93975bf87fb0ea09bb"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/purchase_completed.md",
+      "sha256": "4fc5b6973ed5b9520619914e41f9633308ae3d46f391a57be44e5a1a7c210253"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/single_step_choice.md",
+      "sha256": "63efe3cdf363342eda69522f9c549f11203b53d2afe10af6ebce4eff90e5a53c"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/single_step_choice_emoji.md",
+      "sha256": "ed3593d6b1ff26dfccec515f858304001da1e3739dbc9a4d22dfafb5ebfbbc0c"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/social_proof.md",
+      "sha256": "cae4611e44d020ebe7a1792f91666b1a8d9df2798a226808a830f903f58feccb"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/subscription_handoff.md",
+      "sha256": "dd2e7fed11f1f08ecfa9a969ea0b55d7d41d28c5ab160f6e4a560ee2a7bc2ff3"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/subscription_management.md",
+      "sha256": "291d2c39d414a8ece0c73840b20eed14c86f88700323835c86a518c91382d02d"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/summary_confirmation.md",
+      "sha256": "a92a1a5c7e7072a0ac86f808940f72fd4be38f97624219d2a1e7a04580b73cc6"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/upsell_offer.md",
+      "sha256": "832ffb5506ccdc72b28c839e1b574e5c9ba0c01755fa6c4be105dbe1136b21d0"
+    },
+    {
+      "path": "docs/funnelsgrove/steps/value_prop_story.md",
+      "sha256": "9c62b5c908ffade3dc478b95f67b574817af98d4e8c9359d7db20cccd5eca2b7"
+    },
+    {
+      "path": "funnel-docs.config.json",
+      "sha256": "1d255682f3394a650b2d1046de407d2772cec5049c6ff9872d66e893d30076d4"
+    }
+  ]
+}