# 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.
- Quiz completed counts each unique user who reaches a paywall step.
- `purchase_completed` remains trusted-server-only purchase verification and does not define Quiz completed.
- Browser terminal reach and `funnel_completed` remain lifecycle-only and are not purchase conversions.
- `subscription-started` remains the contract-v3 `purchase_completed` terminal type, and only the trusted backend records the purchase event 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.