@funnelsgrove/cli 0.1.14 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.14",
+  "version": "0.1.18",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "type": "module",
   "bin": {
@@ -10,7 +10,13 @@
   "files": [
     "dist",
     "README.md",
-    "template_docs"
+    "contracts",
+    "template_docs",
+    "template_scaffold",
+    "!template_scaffold/node_modules",
+    "template_validation",
+    "docs-release-history.json",
+    "legacy-docs-catalog.json"
   ],
   "publishConfig": {
     "access": "public"
@@ -18,13 +24,16 @@
   "scripts": {
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "prepack": "npm run build",
+    "prepublishOnly": "node ../../scripts/check-cli-release-dependencies.mjs",
     "test": "vitest run"
   },
   "dependencies": {
-    "commander": "^12.0.0"
+    "@funnelsgrove/runtime": "0.1.59",
+    "commander": "^12.0.0",
+    "typescript": "^5.8.3"
   },
   "devDependencies": {
-    "typescript": "^5.0.0",
+    "@funnelsgrove/analytics": "0.1.36",
     "vitest": "^3.0.0"
   }
 }

package/template_docs/.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"
+    }
+  ]
+}

package/template_docs/AGENTS.md

@@ -1,70 +1,42 @@
 # AGENTS.md
 
-Source-of-truth guide for editing this synced FunnelsGrove funnel. Read the matching topic doc before editing; the docs define the contracts the runtime expects.
+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.
 
-## Find Your Task
+## Route by task
 
-| Task | Read | Edit | Target time |
-| --- | --- | --- | --- |
-| Add or edit a step | [docs/editing-step.md](docs/editing-step.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) | `src/steps/*` + registries + manifest | < 3 min to first preview |
-| Change step order / branching | [docs/editing-flow.md](docs/editing-flow.md) | `src/config/funnel.manifest.ts` | < 2 min |
-| Set up an A/B experiment | [docs/ab-experiments.md](docs/ab-experiments.md) | `src/config/experiments.ts` | < 1 min when variant step exists |
-| Edit copy or images | [docs/editor-and-content.md](docs/editor-and-content.md) | `src/steps/content/*.content.ts` | < 2 min |
-| Edit image loading/performance | [docs/editing-flow.md](docs/editing-flow.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) + [docs/publishing-and-versioning.md](docs/publishing-and-versioning.md) | `src/config/funnel.manifest.ts`, `src/components/FunnelFlow.tsx`, image assets | careful, QA required |
-| Change plans, prices, discounts | [docs/payment-plans-and-discounts.md](docs/payment-plans-and-discounts.md) | `src/config/billing.plans.ts` | careful, read doc fully |
-| Edit paywall or checkout | [docs/payment-plans-and-discounts.md](docs/payment-plans-and-discounts.md) + [docs/step-ui-guidelines.md](docs/step-ui-guidelines.md) | `src/steps/step-32-paywall*.tsx` | careful, QA required |
-| Change colors / fonts | [docs/theme.md](docs/theme.md) | `src/theme/theme.ts` | < 2 min |
-| QA before publish | [docs/qa-checklist.md](docs/qa-checklist.md) | nothing — test and report | as long as it takes |
-| Publish | [docs/publishing-and-versioning.md](docs/publishing-and-versioning.md) | nothing — `fgrove` commands | — |
+| 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) |
 
-Deep dives: [Funnel Runtime Architecture](docs/funnel-runtime-architecture.md), [SDK API Endpoints](docs/sdk-api-endpoints.md), [Analytics](docs/analytics.md), [Meta Pixel and Conversions API](docs/meta-pixel-conversions-api.md).
+## Non-negotiable workflow
 
-## Architecture in 30 Seconds
+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.
 
-The funnel is a small Next.js app on shared packages:
+## Sync safety
 
-- `@funnelsgrove/runtime` — routing, user state, content localization, builder preview, theme.
-- `@funnelsgrove/analytics` — event tracking and A/B assignment (wraps PostHog; never call PostHog directly).
-- `@funnelsgrove/payments` — plans, discounts, Stripe checkout, wallet buttons, shared checkout UI.
-- This repo — product decisions only: step views, content, editor fields, flow manifest, theme, assets, plan ids.
+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.
 
-Most edits touch one step file plus its matching `content/` and `editor/` files, or one config file. If an edit spreads wider than that, stop and re-read the topic doc.
+Contract version: `3`
 
-## Standard Workflow
+Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
 
-1. `fgrove status` — confirm the active project and funnel.
-2. `git status --short` — if local changes exist, checkpoint them before any refresh.
-3. `fgrove github status` — when GitHub is connected and remote is ahead, run `fgrove github pull`, then poll `fgrove github status` until the pull job is completed or skipped before syncing the latest draft into a clean directory and merging the local checkpoint intentionally.
-4. When GitHub is not connected, use `fgrove sync down --funnel <id-or-slug> --dir <temp-dir>` or an already selected `fgrove use` context as the remote source, then merge that clean hosted draft with local changes before editing further.
-5. Make the scoped edit per the topic doc.
-6. `npm run test:run && npm run lint` (or the checks this tree defines).
-7. `npm run dev` — verify in local preview at all four default breakpoints: small 375x667, medium 393x852, large 402x874, and desktop-small 1280x800 ([docs/step-ui-guidelines.md](docs/step-ui-guidelines.md)).
-8. Run the relevant part of [docs/qa-checklist.md](docs/qa-checklist.md).
-9. Ask the user before publishing. If GitHub is connected, commit and push with normal git, run `fgrove github pull`, then poll `fgrove github status` until the pull job is completed or skipped. Do not also run `fgrove sync up` for the same diff.
-10. If GitHub is not connected, run `fgrove sync up --message '<summary>'`.
-11. Publish preview with `fgrove publish --env preview --message '<summary>'`.
-12. QA the preview URL. Production publish only on explicit request, after preview QA.
+## Project-specific context
 
-`fgrove env pull` refreshes the local `.env` when remote project settings changed.
-Do not run `fgrove sync down` over a dirty synced directory unless discarding
-local changes is intentional and `--force` is passed. If `fgrove sync up`
-reports that the remote draft changed since this directory was synced, download
-the current draft into a temp directory, merge local changes, rerun checks, and
-sync again.
-For GitHub-connected funnels, source changes must flow through GitHub first:
-`git push`, then `fgrove github pull`, then publish. Do not mix `fgrove sync up`
-with the same local source diff.
-
-## Behavioral Rules
-
-1. **Think before coding.** State assumptions. If multiple interpretations exist, present them — don't pick silently. If something is unclear, ask before editing.
-2. **Simplicity first.** Minimum code that solves the problem. No speculative abstractions, options, or error handling for impossible states.
-3. **Surgical changes.** Touch only what the request requires. Match existing style. Remove only orphans your own change created. Every changed line should trace to the request.
-4. **Goal-driven execution.** Define the success check before editing ("step renders at all default breakpoints and Continue advances to step-X"), then loop until it passes.
-5. **Image performance locked.** Keep build-time raster compression plus AVIF/WebP variants enabled. For funnel step images, use `funnelManifest.assets` + step `assetIds`, priority/preload only for first-viewport images, and low-priority next-step warming from the shell. Do not preload the whole funnel image set.
-6. **Meaningful URLs.** New step `path` values are public product routes, so use readable slugs like `/motivation`, `/fitness-goal`, or `/email-capture`. Sequential ids and `step-NN-*` filenames are okay for ordering, but do not create public routes like `/step-1`.
-7. **Flow labeling hygiene.** When changing `edgesByStepId`, keep manifest `branches` current for conditional paths that own steps before reconverging. Keep builder metadata ClaimBee-style and source-readable: `edgesByStepId` keys/targets and `branches: [...]` must use inline string literals, not `someStep.id` variables or a `branches: flowBranches` indirection. Each branch needs a readable `name`, answer-derived `label` such as `yes-branch`, useful `tags`, and the owned `stepIds`. Running experiment variants need labels/tags like `paywall-test-control` and `paywall-test-variant-b`; stopped A/B variants or other inactive screens should keep stable tags and remain unreachable from the default flow so builder marks them `unused`.
-
-Architecture docs are part of the change: if you change routing, runtime state, SDK contracts, URL handoff parameters, checkout behavior, analytics events, or shared package boundaries, update the matching doc in the same change.
-
-Preserve existing step ids, paths, and answer keys unless the task is an explicit migration — they feed routes, persisted answers, analytics, and publish history.
+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_docs/CLAUDE.md

@@ -1,3 +1 @@
 @AGENTS.md
-
-Claude Code should use `AGENTS.md` as the shared agent guidance for this synced funnel. Merge those rules with the user's current request and any project-specific instructions.

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