@funnelsgrove/cli 0.1.15 → 0.1.18

package/template_scaffold/docs/funnelsgrove/steps/single_step_choice_emoji.md

@@ -0,0 +1,122 @@
+# `single_step_choice_emoji`
+
+## Use when / do not use when
+
+Use when exactly one emoji-led option completes on selection. Do not use when emoji is merely decorative on a standard list or when multiple answers are allowed.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/single_step_choice_emoji -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `single_step_choice_emoji`
+- Family: `choice`
+- Description: Exactly one emoji-led option is selected.
+- Action owner: `step`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: _none_
+- Allowed kinds: _None_
+- Allowed semantic events: _None_
+- Forbidden capabilities: `email-capture`, `checkout`, `subscription-management`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+- Cardinality: `one`
+- Presentation: `emoji`
+- Completion: `selection`
+- Allow empty config: `false`
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+- `choice-write` must be owned by `useStepChoices`.
+
+#### Reserved identities
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const choice = { answerKey: 'goalFeeling' } as const;
+
+const manifestStep = {
+  id: 'goal-feeling',
+  name: 'goal-feeling',
+  path: '/goal-feeling',
+  filePath: 'src/steps/step-goal-feeling.tsx',
+  componentKey: 'stepGoalFeeling',
+  type: 'single_step_choice_emoji',
+  choice,
+  title: 'How do you want to feel?',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'goal-feeling',
+  name: 'goal-feeling',
+  type: 'single_step_choice_emoji',
+  choice,
+  figmaNodeId: 'golden:single-step-choice-emoji',
+  title: 'How do you want to feel?',
+  description: 'Select exactly one emoji-led feeling.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'single_step_choice_emoji',
+  manifestStep,
+  componentMeta,
+  options: [
+    { id: 'focused', label: 'Focused', emoji: '🎯' },
+    { id: 'calm', label: 'Calm', emoji: '🌿' },
+  ],
+  persistedAnswer: 'focused',
+  helper: 'useStepChoices',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/single_step_choice_emoji -->
+
+## Interaction and persisted answer shape
+
+Declare `choice.answerKey`; every option includes an emoji and stable ID. Persist the selected ID as a scalar string.
+
+## Automatic lifecycle events
+
+`useStepChoices` coordinates persistence, controller completion, and manifest routing. Preview suppresses provider delivery.
+
+## Required semantic conversions
+
+None.
+
+## Approved shared helpers
+
+Use `useStepChoices` and the shared emoji-choice rendering pattern.
+
+## MUST rules
+
+- Provide meaningful emoji data for every option.
+- Keep IDs stable when labels or emoji change.
+
+## NEVER rules
+
+- Never persist emoji or labels as the answer.
+- Never bypass the choice helper.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `single_step_choice_emoji.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm keyboard and pointer selection both save one stable ID, show the intended emoji, and advance once.

package/template_scaffold/docs/funnelsgrove/steps/social_proof.md

@@ -0,0 +1,110 @@
+# `social_proof`
+
+## Use when / do not use when
+
+Use for testimonials, reviews, credibility, or evidence. Do not use for general benefits, a survey, or an offer.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/social_proof -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `social_proof`
+- Family: `content`
+- Description: Testimonials, reviews, credibility, or evidence.
+- 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: 'member-results',
+  name: 'member-results',
+  path: '/member-results',
+  filePath: 'src/steps/step-member-results.tsx',
+  componentKey: 'stepMemberResults',
+  type: 'social_proof',
+  title: 'Member results',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'member-results',
+  name: 'member-results',
+  type: 'social_proof',
+  figmaNodeId: 'golden:social-proof',
+  title: 'Member results',
+  description: 'Show attributable testimonials and evidence.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'social_proof',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'shared-shell',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/social_proof -->
+
+## Interaction and persisted answer shape
+
+This content screen does not persist an answer. Standard progression belongs to the shared shell.
+
+## Automatic lifecycle events
+
+The controller owns lifecycle tracking and suppresses provider delivery in preview.
+
+## Required semantic conversions
+
+None.
+
+## Approved shared helpers
+
+Use shared content/image components and the shared action bar.
+
+## MUST rules
+
+- Keep proof content attributable and builder-editable where required.
+- Keep metadata parity.
+
+## NEVER rules
+
+- Never turn proof interactions into invented conversion events.
+- Never call providers directly.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `social_proof.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm all proof content and assets render accessibly at supported breakpoints and Continue follows manifest routing.

package/template_scaffold/docs/funnelsgrove/steps/subscription_handoff.md

@@ -0,0 +1,113 @@
+# `subscription_handoff`
+
+## Use when / do not use when
+
+Use for a non-terminal app, store, or deep-link handoff. Do not use for the canonical post-purchase registration-completion terminal.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/subscription_handoff -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `subscription_handoff`
+- Family: `commerce`
+- Description: A non-terminal app, store, or deep-link handoff.
+- Action owner: `step`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: `subscription-handoff`
+- Allowed kinds: `subscription-handoff`
+- Allowed semantic events: _None_
+- Forbidden capabilities: `choice-write`, `email-capture`, `checkout`, `subscription-management`, `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-handoff` must be owned by `runtime-handoff-helper`.
+
+#### Reserved identities
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'open-app',
+  name: 'open-app',
+  path: '/open-app',
+  filePath: 'src/steps/step-open-app.tsx',
+  componentKey: 'stepOpenApp',
+  type: 'subscription_handoff',
+  kind: 'subscription-handoff',
+  title: 'Continue in the app',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'open-app',
+  name: 'open-app',
+  type: 'subscription_handoff',
+  kind: 'subscription-handoff',
+  figmaNodeId: 'golden:subscription-handoff',
+  title: 'Continue in the app',
+  description: 'Continue through a non-terminal app handoff.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'subscription_handoff',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime handoff helper',
+  isRegistrationCompletion: false,
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/subscription_handoff -->
+
+## Interaction and persisted answer shape
+
+Build the outbound destination through the runtime handoff helper. This screen persists no choice answer.
+
+## Automatic lifecycle events
+
+Leaving through the handoff is not funnel registration completion. The controller owns the step outcome.
+
+## Required semantic conversions
+
+None. This non-terminal handoff must not emit funnel or registration completion.
+
+## Approved shared helpers
+
+Use the runtime subscription-handoff helper with the safe default `SubscriptionHandoffScreen` completion mode of `step`; never opt a non-terminal handoff into `completionMode="funnel"`.
+
+## MUST rules
+
+- Treat the destination as configuration/runtime data.
+- Keep non-terminal semantics explicit.
+
+## NEVER rules
+
+- Never emit trusted `purchase_completed`, `registration_completed`, or terminal `funnel_completed`.
+- Never build an unvalidated deep link by string concatenation.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `subscription_handoff.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test installed/uninstalled destinations, query propagation, return behavior, and absence of completion conversions.

package/template_scaffold/docs/funnelsgrove/steps/subscription_management.md

@@ -0,0 +1,112 @@
+# `subscription_management`
+
+## Use when / do not use when
+
+Use to inspect or manage an existing subscription. Do not use for an acquisition paywall, cancellation save offer, or app handoff.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/subscription_management -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `subscription_management`
+- Family: `commerce`
+- Description: A screen for managing or inspecting an existing subscription.
+- Action owner: `step`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: `manage-subscription`
+- Allowed kinds: `manage-subscription`
+- 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
+
+- `manage-subscription`: id=`manage-subscription`, name=`manage-subscription`; type=`subscription_management`; kind=`manage-subscription`; unique=`true`
+
+#### Golden fixture source
+
+```ts
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'manage-subscription',
+  name: 'manage-subscription',
+  path: '/manage-subscription',
+  filePath: 'src/steps/step-manage-subscription.tsx',
+  componentKey: 'stepManageSubscription',
+  type: 'subscription_management',
+  kind: 'manage-subscription',
+  title: 'Manage subscription',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'manage-subscription',
+  name: 'manage-subscription',
+  type: 'subscription_management',
+  kind: 'manage-subscription',
+  figmaNodeId: 'golden:subscription-management',
+  title: 'Manage subscription',
+  description: 'Inspect and manage an existing subscription.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'subscription_management',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime subscription helpers',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/subscription_management -->
+
+## Interaction and persisted answer shape
+
+Load and mutate subscription state through runtime subscription helpers. This screen does not persist funnel choice answers.
+
+## Automatic lifecycle events
+
+The controller owns step lifecycle; subscription APIs own account-state changes.
+
+## Required semantic conversions
+
+None unless a separately defined server-owned subscription event exists.
+
+## Approved shared helpers
+
+Use runtime subscription-management helpers and manifest routing.
+
+## MUST rules
+
+- Preserve the reserved management identity.
+- Refresh visible state after a successful management action.
+
+## NEVER rules
+
+- Never expose secrets or call a provider with browser credentials.
+- Never relabel this screen as a paywall.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `subscription_management.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test loading, empty state, action success/failure, refresh, back/exit, and exact reserved metadata.

package/template_scaffold/docs/funnelsgrove/steps/summary_confirmation.md

@@ -0,0 +1,110 @@
+# `summary_confirmation`
+
+## Use when / do not use when
+
+Use for a summary, review, or confirmation before the next action. Do not use for choice collection, a progress reveal, or an offer.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/summary_confirmation -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `summary_confirmation`
+- Family: `content`
+- Description: A summary, review, or confirmation before the next action.
+- Action owner: `either`
+- 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: 'review-plan',
+  name: 'review-plan',
+  path: '/review-plan',
+  filePath: 'src/steps/step-review-plan.tsx',
+  componentKey: 'stepReviewPlan',
+  type: 'summary_confirmation',
+  title: 'Review your plan',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'review-plan',
+  name: 'review-plan',
+  type: 'summary_confirmation',
+  figmaNodeId: 'golden:summary-confirmation',
+  title: 'Review your plan',
+  description: 'Review existing answers before continuing.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'summary_confirmation',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'either',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/summary_confirmation -->
+
+## Interaction and persisted answer shape
+
+Read existing answers through runtime state. Only edit an answer through its owning input/choice flow.
+
+## Automatic lifecycle events
+
+The controller owns completion and exit. Preview suppresses provider delivery.
+
+## Required semantic conversions
+
+None.
+
+## Approved shared helpers
+
+Use runtime answer readers, shared action UI, and manifest routing.
+
+## MUST rules
+
+- Render stable answer meaning, not internal object dumps.
+- Keep confirmation and edit routes manifest-owned.
+
+## NEVER rules
+
+- Never invent a completion conversion for viewing a summary.
+- Never mutate answer storage directly.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `summary_confirmation.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm empty/populated answers, edit-return behavior, accessibility, and exactly-once completion through the controller.

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