@funnelsgrove/cli 0.1.15 → 0.1.18

package/template_docs/docs/editor-and-content.md

@@ -1,58 +0,0 @@
-# Editor and Content
-
-Editable step content is a runtime contract. The step view should read from typed content, not from scattered hardcoded strings, when the value is copy, image, legal text, pricing label, FAQ, testimonial, or builder-editable UI.
-
-## Content Files
-
-Each step content file exports a typed `LocalizedStepContent<T>`:
-
-```ts
-export const stepContent = {
-  defaultLocale: 'en',
-  locales: {
-    en: {
-      headline: ['People getting', 'free money', 'know one secret'],
-      artwork: { src: '/figma/example.png', alt: '' },
-    },
-  },
-} as const satisfies LocalizedStepContent<StepLocaleContent>;
-```
-
-The runtime validates that a default locale exists and resolves locale from funnel attributes (`browserLanguage`, `language`, `locale`) or browser locale. In preview, builder content patches are merged before the step renders.
-
-Use runtime item types where possible:
-
-- `StepImage` for images.
-- `ChoiceItem`, `InfoItem`, `QuoteItem`, `QaItem`, `LinkItem`, `ReasonItem`, `StoreLinkItem`, `PlanPresentationItem` for lists.
-- `CountryPricingProfile` for country-specific plan ordering/defaults.
-
-## Editor Files
-
-Each editor file exports `readonly StepEditorSection[]`. A field's `path` must match the content object path:
-
-```ts
-{
-  id: 'hero.image',
-  label: 'Hero image',
-  kind: 'image',
-  path: 'hero.image',
-}
-```
-
-Supported field kinds are `text`, `textLines`, `textarea`, `image`, `boolean`, `select`, `list`, and `pricingProfile`. List fields must use a preset such as `choiceItems`, `infoItems`, `quoteItems`, `qaItems`, or `linkItems`.
-
-Only expose fields the builder should edit. Do not add spare content fields for possible future use.
-
-## Variables
-
-For builder variables, set `supportsVariables: true` on text-capable fields only. Editor variables map `user.*` tokens to answer paths, then runtime interpolation replaces `{{ user.token }}` style values in supported fields. Universal variables also support simple `{user_id}` replacement at render time.
-
-Keep variable use obvious. If a step depends on a value from an earlier step, make sure that earlier step writes a stable answer key.
-
-## Agent Rules
-
-- Keep copy, images, FAQ, testimonials, legal strings, and checkout labels in content files.
-- Keep layout decisions in the step file.
-- Keep editor sections aligned with the content shape.
-- Keep `src/steps/step-content.registry.ts` in sync when adding or renaming content/editor files.
-- Use checked-in public assets (`/paywall/...`, `/figma/...`, etc.); do not leave temporary localhost asset URLs.

package/template_docs/docs/funnel-runtime-architecture.md

@@ -1,125 +0,0 @@
-# Funnel Runtime Architecture
-
-This doc explains the runtime contracts a synced funnel should preserve. Update this file when changing funnel architecture, routing, identity handoff, SDK payloads, payments, subscriptions, or analytics.
-
-## Runtime Boundary
-
-A funnel is a small Next.js app that owns product-specific steps, content, assets, theme, and billing plan ids. Shared packages own the reusable runtime behavior:
-
-- `@funnelsgrove/runtime`: routing, user state, URL user attributes, SDK calls, preview mode, content localization, subscription handoff, runtime config, and theme variables.
-- `@funnelsgrove/payments`: Stripe plan resolution, discounts, checkout sessions, wallet/card checkout UI, and manage-subscription UI.
-- `@funnelsgrove/analytics`: canonical analytics events and provider delivery.
-
-Keep funnel code thin. Step files should use the shared runtime/payment/analytics surfaces instead of calling raw SDK endpoints, Stripe, PostHog, or browser routing directly.
-
-## Flow And Routing
-
-The local source of truth is `src/config/funnel.manifest.ts`.
-
-- `steps[]` defines every routable step with stable `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, and asset references.
-- `edgesByStepId` defines normal and conditional navigation.
-- `entryPoints` lets public routes such as `/paywall` and `/manage-subscription` land directly on a step.
-- `src/runtime/step-registry.ts` maps manifest step ids to React components.
-
-Use `useFunnel()` navigation (`goNext`, `goChoice`, `goToStep`) so runtime history, experiments, and step tracking remain consistent.
-
-## User Identity
-
-The runtime persists a local user id under the funnel-scoped local storage key `funnel:<funnelId>:user-id`. Public URLs can also pass user attributes:
-
-- `user_id`: canonical public funnel user id when a known user is being resumed.
-- `email`: shopper/contact email. The runtime validates it and syncs it into the funnel user profile.
-- `name`, `fullName`, `full_name`: optional profile name aliases.
-- `stripe_customer_id`: Stripe customer id used by subscription management links.
-
-At startup, the flow controller bootstraps a user through `apiService.bootstrapSession(...)` with the URL or local user id, email/name, and first-touch attribution. Step answers are stored in runtime attributes and persisted through `apiService.updateUser(...)` as `document.progress.attributes` plus completed step records.
-
-Do not invent new identity query names casually. If a new URL parameter becomes part of the funnel contract, add it to the URL attribute parser, SDK docs, and this file.
-
-## Paywall Entry
-
-Paywall routes can be opened directly, usually as `/paywall`.
-
-Supported identity handoff:
-
-- `/paywall?user_id=u_123`: resume a known funnel user and preserve that id through checkout metadata.
-- `/paywall?email=user@example.com`: seed/sync the shopper email and pass it as Stripe `customerEmail`.
-- `/paywall?user_id=u_123&email=user@example.com`: preferred when both are known.
-
-Email-only links are useful for prefilled checkout and later private user lookup by email, but `user_id` is the stronger join key for existing answers, attribution, and subscription reconciliation.
-
-Paywall checkout should use `@funnelsgrove/payments` helpers. Checkout payloads must include the selected plan, amount, coupon, checkout mode, runtime config, `user_id` when available, and `customerEmail` when available. Stripe sessions receive `client_reference_id` and FunnelsGrove metadata with plan id, price id, user id, environment, funnel id, funnel version id, coupon id, and customer email.
-
-Success/return URLs should route to the subscription-started step and preserve `user_id`, for example `/subscription-started?user_id=u_123&source=stripe-elements`.
-
-## Subscription Started Handoff
-
-The subscription-started step uses `SubscriptionHandoffScreen` and `resolveSubscriptionHandoff(...)`.
-
-The handoff requires a user id. App store URLs, universal links, and deep links may include `{user_id}` and `{email}` templates; runtime also appends `user_id` and first-touch attribution parameters when it can parse the URL.
-
-This step is also the right place to track payment return events such as `payment_checkout_succeeded` or `payment_checkout_returned`. Keep raw payment objects and secrets out of analytics metadata.
-
-## Manage Subscription
-
-The manage-subscription route is a public customer support route, usually `/manage-subscription`.
-
-Supported identity handoff:
-
-- `/manage-subscription?user_id=u_123`: resolve the funnel user, then resolve Stripe customer/subscriptions from the linked user, user document, or billing records.
-- `/manage-subscription?stripe_customer_id=cus_123`: resolve subscriptions directly by Stripe customer id when the funnel user id is unavailable.
-- `/manage-subscription?user_id=u_123&stripe_customer_id=cus_123`: preferred for support/admin generated links.
-
-The runtime calls:
-
-- `GET /sdk/public/subscriptions?user_id=...&stripe_customer_id=...&funnelId=...`
-- `POST /sdk/public/subscriptions/:subscriptionId/:action` with `action` of `cancel` or `renew`
-
-If neither `user_id` nor `stripe_customer_id` is available, the list endpoint returns an empty public summary and mutation rejects the request. The UI should show an empty/error state and the support email from runtime config.
-
-## Webhooks And Reconciliation
-
-Stripe webhooks reconcile payment/subscription state back into the funnel user. The important join points are:
-
-- Stripe metadata `userId` and `customerEmail`.
-- Stripe `client_reference_id`.
-- provider customer id (`stripe_customer_id` / `providerCustomerId`).
-- stored funnel user subscription fields and document subscription snapshots.
-
-Webhook reconciliation updates the funnel user subscription status, Stripe customer/subscription ids, subscription document snapshots, billing records, analytics, and project webhooks. When editing checkout metadata or URL handoff, verify the webhook still has enough information to find the correct funnel user.
-
-## Analytics
-
-The flow controller emits canonical runtime events:
-
-- `step_start`
-- `step_end`
-- `step_engaged` on the first step after the engagement threshold
-
-The analytics provider may receive mapped names such as `step_started` and `step_completed`.
-Paywalls should track checkout intent and completion through `@funnelsgrove/analytics` with plan id, provider plan id, coupon id, amount, and environment. Do not send personal data, SDK keys, Stripe secrets, or raw provider responses.
-Completed Registration is tracked by the server only when the app successfully calls `POST /sdk/public/users/:user_id/claim_subscription` after login/signup.
-
-## Preview Runtime
-
-Builder preview is intentionally different from production:
-
-- normal SDK writes are skipped or replaced with local fallbacks;
-- manage-subscription uses a preview fallback payload;
-- runtime mode and paywall plans can be patched by the builder preview bridge;
-- checkout may force test mode when the preview payment key is active.
-
-Do not make preview-only shortcuts the production contract.
-
-## Architecture Change Checklist
-
-When a funnel architecture change touches any item below, update `template_docs` with the new behavior:
-
-- route paths, manifest step ids, entry points, or step kinds;
-- runtime user state, URL parameters, attribution, or answer persistence;
-- SDK endpoint paths, query/body fields, response shape, or auth headers;
-- payment plan mapping, checkout metadata, return URLs, discounts, or Stripe mode resolution;
-- manage-subscription identity resolution or mutation behavior;
-- subscription handoff links, app/deep-link templates, or post-checkout routing;
-- analytics event names or required metadata;
-- preview/editor runtime behavior.

package/template_docs/docs/meta-pixel-conversions-api.md

@@ -1,50 +0,0 @@
-# Meta Pixel and Conversions API
-
-Meta analytics is provider-specific. Keep funnel code on the `@funnelsgrove/analytics` API surface; do not call `fbq`, Meta Pixel, or Conversions API directly from funnel steps.
-
-## Browser Pixel Events
-
-The browser Pixel is initialized by `@funnelsgrove/analytics` when both public env vars are set:
-
-- `NEXT_PUBLIC_META_PIXEL_ENABLED=true`
-- `NEXT_PUBLIC_META_PIXEL_ID=<pixel id>`
-
-Browser events:
-
-- `publicAnalyticsSdk.trackFirstStepViewed(...)` sends Meta `ViewContent` when the user lands on the real first funnel page.
-- `publicAnalyticsSdk.trackFirstStepClicked(...)` is still supported for funnels or experiments that need click-specific first-step analytics. It also maps to Meta `ViewContent`.
-- `checkout_started` maps to Meta `InitiateCheckout`.
-- `checkout_completed` maps to Meta `AddPaymentInfo`.
-
-Do not fire both `trackFirstStepViewed(...)` and `trackFirstStepClicked(...)` for the same intended conversion unless the product explicitly wants two separate analytics events. Preview runtime must not send normal Pixel events.
-
-The browser Pixel owns browser attribution automatically through Meta cookies such as `_fbp` and `_fbc`.
-
-## Server Conversions API Events
-
-Server-side Meta events go through the API analytics service and Facebook Conversions API. Project env requires:
-
-- `META_CONVERSIONS_ACCESS_TOKEN=<server token>`
-- Optional test helper: `META_TEST_EVENT_CODE=<Meta test code>`
-
-Trusted server events currently come from Stripe webhooks:
-
-- Paid checkout session, invoice, or payment intent sends Meta `Purchase`.
-- Active or trialing subscription webhook sends Meta `Subscribe`.
-
-Server events use the funnel user id as Meta `external_id`; do not use the funnel user id as an event id. Event ids must be unique per event. Use one generated event id for a browser/server pair only when both sides represent the same user action and should be deduplicated.
-
-## Attribution Matching
-
-Runtime stores URL/referrer attribution in `funnelUser.document.attribution`.
-
-Keep `fbclid` in attribution. The API can derive Meta `fbc` from stored `fbclid` and the attribution capture time for later Stripe webhook conversions. The API also sends known email, funnel user id, user agent, and other available match fields.
-
-Do not invent or strip attribution URL params unless the funnel runtime attribution docs and SDK contract are updated in the same change.
-
-## Agent Rules
-
-- Use analytics package helpers instead of raw Meta calls.
-- When changing first-page routing, verify `ViewContent` still fires only for the real first landing page and not preview runtime.
-- When changing checkout or subscription behavior, verify the corresponding server CAPI event still has project id, funnel user id, event id, currency/value where available, and stored attribution.
-- Do not send secrets, raw Stripe objects, access tokens, or full payment payloads to browser analytics.

package/template_docs/docs/payment-plans-and-discounts.md

@@ -1,106 +0,0 @@
-# Payment Plans and Discounts
-
-Payments are handled through `@funnelsgrove/payments`. Funnel steps should use the shared payment module instead of building raw Stripe calls.
-
-## Plan Sources
-
-Local plans live in `src/config/billing.plans.ts`. A plan catalog is keyed by stable funnel keys (`primary`, `secondary`, `tertiary`) and each plan includes:
-
-- `projectPlanId`: FunnelsGrove project plan id.
-- `providerPlanId`: Stripe price id.
-- `title`, `priceLabel`, `perDayAmount`, `amountCents`.
-- Optional `featuredTag`, `oldPriceLabel`, `checkoutSummaryLabel`, `billingInterval`, `billingIntervalCount`, `isDefault`.
-
-ClaimBee-style funnels may keep separate test/live catalogs with `createRuntimeModeBillingPlanCatalog(...)` and choose the active catalog through `useRuntimeMode()` plus checkout mode resolution.
-
-## Runtime Resolution
-
-Use the shared helpers:
-
-- `buildConfigPaywallPlans(...)` for local catalogs.
-- `useResolvedPaywallPlans(...)` when the funnel can load synced project Stripe plans.
-- `getDefaultPlanId(...)`, `findPaywallPlan(...)`, and `getPaywallPlanSelectionValue(...)` for selection.
-- `usePreviewStepPaywallPlans(stepId)` so builder paywall plan edits appear in preview.
-
-If a catalog is only a mapping of `{ projectPlanId }`, the payment module can load remote project plans from `/sdk/public/payments/plans` and map them back to funnel keys.
-
-## Discounts
-
-Discounts use `BillingDiscountList` or `BillingDiscountCatalog` and are resolved by `buildBillingDiscountCatalog(...)`. The current ClaimBee pattern has two stages:
-
-- First stage: coupon id, percent, duration.
-- Second stage: stronger coupon id, percent, duration, and previous percent.
-
-Use `resolvePaywallDiscountState(...)`, `advancePaywallDiscountState(...)`, `activateSecondPaywallDiscount(...)`, `serializePaywallDiscountState(...)`, and `buildDiscountedPaywallPlans(...)`. Store discount state through runtime paywall state helpers (`readPaywallStateValue`, `updatePaywallStateValue`) so it is scoped by funnel id.
-
-### Discount on Closing Checkout
-
-The standard two-stage flow, wired in the paywall step:
-
-1. Paywall opens with the first-stage discount applied to plan cards.
-2. The checkout controller's `onFirstCheckoutClosed` callback fires when the visitor closes the card checkout without paying. The paywall opens `SharedCheckoutSpecialOfferDialog` (image, discount label, accept button — copy lives in the paywall content file).
-3. Accepting calls `activateSecondPaywallDiscount(...)`, which swaps to the stronger second-stage coupon, restarts its window, and re-renders plans via `buildDiscountedPaywallPlans(...)`.
-4. The next checkout open carries the second-stage coupon id in its payload.
-
-Keep both stages testable: QA must verify stage one on open and stage two after a checkout close ([qa-checklist.md](qa-checklist.md), paywall item 5).
-
-## Checkout
-
-Prefer shared Stripe surfaces:
-
-- `useStripeSubscriptionCheckoutSession(...)` for subscription checkout sessions.
-- `SharedStripeCheckoutV2Dialog` for card checkout UI.
-- `ApplePaySubscriptionCheckoutSlot` and `GooglePaySubscriptionCheckoutSlot` for wallet buttons.
-- `StripeExpressCheckoutButton` / `StripePlanSelector` for older paywall variants.
-
-Runtime config should come from `runtimePublicConfig` through a local `src/runtime/checkout-runtime-config.ts`. Include `apiBaseUrl`, `funnelId`, and the SDK publishable key. Preview seed keys may resolve to the preview payment key and force test checkout mode.
-
-### Shared Checkout V2 and Wallet Slots
-
-Subscription paywalls with on-page wallet buttons should share one `useStripeSubscriptionCheckoutSession(...)` instance across the manual card checkout and wallet checkout. Do not build funnel-local Stripe PaymentIntent or Express Checkout flows.
-
-- Keep funnel-specific checkout orchestration local when it includes product layout, analytics callbacks, return URL branching, or email prompt copy. The shared UI boundary is `SharedStripeCheckoutV2Dialog`; do not add another shared wrapper that duplicates a funnel's paywall composition.
-- Use `SharedStripeCheckoutV2Dialog` for the manual/card checkout modal. Open it from the paywall CTA after the checkout session has an `activeClientSecret` and `stripePromise`.
-- Render real wallet slots on the paywall with `ApplePaySubscriptionCheckoutSlot` and `GooglePaySubscriptionCheckoutSlot`, usually above the manual/card CTA. Pass the same checkout session, selected plan amount, return URL, customer details, summary label, success handler, and any `beforeConfirm` logic used to finalize email or analytics metadata.
-- Use `usePlatformWalletPaymentMethods()` to decide which slots to render. Desktop web can show Apple Pay and Google Pay; iOS shows Apple Pay; Android shows Google Pay.
-- Track each slot's `onAvailabilityChange` result by the current `checkoutSession.intentKey`. When opening `SharedStripeCheckoutV2Dialog`, derive `initialWalletAvailable` from the current intent's confirmed wallet availability and pass it into the dialog so checkout can show the wallet tab immediately when a wallet is already known to be available.
-- Treat unknown wallet availability as `null`, not `false`. Only hide/fallback from a wallet after Stripe or the shared slot reports that wallet unavailable.
-- Treat Checkout Session/API preparation failures as retryable checkout failures, not wallet unavailability. A failed `prepareWalletCheckout()` should leave the wallet slot in unknown availability and show the real clickable fallback placeholder after loading stops; only Stripe readiness/availability reports should mark a wallet unavailable.
-- Suspend paywall wallet slots while the shared checkout dialog or another blocking offer modal is open, so two Stripe Express Checkout elements do not compete for the same active checkout session.
-- If checkout starts without a known customer email, first try to resolve it from a known `user_id` or `stripe_customer_id`. Only show an email prompt when there is no known identity to fetch from, or that lookup returns no email.
-- Before publishing payment changes, run the shared wallet smoke helper from `@funnelsgrove/payments` against local and preview paywall URLs. The package script is `npm run smoke:wallet --workspace @funnelsgrove/payments -- --url <paywall-url>` and accepts selector overrides through CLI flags or `WALLET_SMOKE_*` env vars.
-
-## Paywall Identity Handoff
-
-Paywall steps may be opened directly by support/admin links:
-
-- `/paywall?user_id=u_123` resumes a known funnel user and carries that id into checkout metadata.
-- `/paywall?email=user@example.com` seeds the runtime user email and Stripe `customerEmail`.
-- `/paywall?user_id=u_123&email=user@example.com` is preferred when both are known.
-
-`user_id` is the strongest join key for answers, attribution, checkout metadata, and webhook reconciliation. Email-only handoff is useful for prefilled checkout and private user lookup, but do not treat it as a full replacement for `user_id` when exact progress/subscription state is required.
-
-Checkout return URLs should route to the subscription-started step and preserve the user id, for example `/subscription-started?user_id=u_123&source=stripe-elements`.
-
-## Manage Subscription Handoff
-
-Manage subscription is a customer support route, usually `/manage-subscription`.
-
-Supported links:
-
-- `/manage-subscription?user_id=u_123`
-- `/manage-subscription?stripe_customer_id=cus_123`
-- `/manage-subscription?user_id=u_123&stripe_customer_id=cus_123`
-
-The runtime calls `apiService.getManageSubscriptions()` and `apiService.updateSubscription(...)`, which send `user_id`, `stripe_customer_id`, and `funnelId` to the public subscriptions SDK endpoints. If neither id is present, the list endpoint returns an empty summary and mutation is rejected.
-
-Generated support/admin links should include `user_id` and add `stripe_customer_id` when the paid customer id is known.
-
-## Agent Rules
-
-- Never change a live `projectPlanId`, `providerPlanId`, coupon id, or amount casually.
-- Keep displayed price, discounted price, amount cents, coupon id, checkout payload, and analytics metadata in sync.
-- Keep paywall, checkout, subscription-started, and manage-subscription identity handoff parameters in sync with [Funnel Runtime Architecture](funnel-runtime-architecture.md).
-- Track checkout starts/completions with plan id, provider plan id, coupon id, amount, and environment.
-- Keep legal, renewal, guarantee, support, and button labels in content files.
-- Test test-mode and live-mode plan resolution separately when a payment change affects both.

package/template_docs/docs/publishing-and-versioning.md

@@ -1,117 +0,0 @@
-# Publishing and Versioning
-
-Local edits are not public until they are synced and published. Sync creates or patches a draft version. Publish deploys that draft.
-
-## CLI Flow
-
-```bash
-fgrove status
-git status --short
-fgrove github status
-fgrove publish --env preview --message '<summary>'
-```
-
-Before syncing down over an existing synced directory, check local changes. If
-`git status --short` shows local edits, checkpoint them first. `fgrove sync
-down` refuses to overwrite a dirty synced directory by default; use `--force`
-only when discarding local changes is intentional.
-
-When GitHub is connected and its branch is ahead, run `fgrove github pull` to
-pull GitHub into the hosted draft, then poll `fgrove github status` until the
-pull job is completed or skipped. Sync that latest draft into a clean directory
-and merge local changes intentionally before continuing.
-
-For GitHub-connected funnels, source changes must be pushed to GitHub first,
-then pulled into the hosted draft:
-
-```bash
-git push
-fgrove github pull
-fgrove github status
-fgrove publish --env preview --message '<summary>'
-```
-
-Poll `fgrove github status` until the pull job is completed or skipped before
-publishing. Do not run `fgrove sync up` for the same source diff; the CLI and
-API reject draft source sync for GitHub-connected funnels.
-
-When GitHub is not connected, the hosted draft is the remote source of truth.
-Download it into a temporary clean directory with `fgrove sync down --funnel
-<id-or-slug> --dir <temp-dir>` or an already selected `fgrove use` context,
-compare it with local changes, merge intentionally, rerun checks, then `fgrove
-sync up`.
-
-For funnels without GitHub, sync local source directly to the hosted draft:
-
-```bash
-fgrove sync up --message '<summary>'
-fgrove publish --env preview --message '<summary>'
-```
-
-If `fgrove sync up` reports that the remote draft changed since the local
-directory was synced, do not retry blindly. Download the current draft into a
-temporary clean directory, merge local changes against it, rerun checks, and
-sync again.
-
-Refresh the ignored local `.env` from the remote project when project settings change:
-
-```bash
-fgrove env pull
-# or, from outside the synced funnel directory:
-fgrove env pull --dir ./path/to/local-funnel
-```
-
-Only publish production when explicitly requested:
-
-```bash
-fgrove publish --env production --domain <domain> --message '<summary>'
-```
-
-Production publish requires a domain. Preview publish returns a deployment URL, version sequence, and version id.
-
-## Publish Image Optimization
-
-Publish builds reduce raster image size before upload. Keep this path enabled:
-PNG/JPEG sources are compressed, AVIF/WebP variants are generated for supported
-browsers, and the original image remains the fallback. Do not bypass this with
-remote funnel-critical image URLs.
-
-After publishing image edits or a production candidate, check the deployment
-metadata, CLI output, or `publishBuild.stageTimings.imageVariants`. If the
-image-variant stage is missing or unavailable, report that explicitly before
-calling the publish ready.
-
-## Local Sync Contract
-
-The CLI writes `.funnelsgrove-sync.json` into the local tree. Keep it there. It
-records workspace id, funnel id, current draft version id, and source hashes so
-later `sync up` can patch only changed/deleted files and detect stale remote
-drafts before overwriting them.
-
-Local-only files are excluded from upload:
-
-- `.env`, `.env.local`, `.env.*` except `.env.example`.
-- `.funnelsgrove-sync.json`.
-- `node_modules`.
-- `.next`.
-- `out`.
-
-The local `.env` is runtime material generated from remote project/funnel settings. Use `fgrove env pull` to refresh it without replacing source files.
-
-Do not edit generated build output as the source of truth.
-
-## Agent Rules
-
-- Run `fgrove status` before syncing.
-- Check local changes before `sync down`; checkpoint or merge instead of
-  overwriting.
-- For GitHub-connected funnels, push with normal git, then run `fgrove github
-  pull`; do not run `fgrove sync up` for the same source change.
-- Use clear sync and publish messages.
-- Sync the hosted draft before publishing: GitHub-connected funnels use normal
-  `git push` plus `fgrove github pull`; funnels without GitHub use `fgrove sync
-  up`.
-- Publish preview first and verify the returned URL.
-- If preview verification fails, fix locally, run checks, sync the hosted draft
-  again through the correct source path, and publish a new preview.
-- Do not production publish without explicit instruction and target domain.

package/template_docs/docs/qa-checklist.md

@@ -1,80 +0,0 @@
-# QA Checklist
-
-What to test, where to test it, and what blocks a publish. QA can take as long as it needs — it is the gate before anything user-facing ships. Scale the scope to the edit: a copy tweak needs the affected step only; anything touching flow, paywall, checkout, pricing, identity, or experiments needs the full list.
-
-## Where
-
-| Stage | URL | When |
-| --- | --- | --- |
-| Local | `npm run dev` → `http://localhost:3000` | Always, before sync |
-| Preview | URL returned by `fgrove publish --env preview` | Before any production publish |
-| Production | Live domain | After production publish |
-
-A production publish without a QA-passed matching preview build is a blocker unless the user explicitly accepts the risk.
-
-## 1. Flow Coverage
-
-- Open the first step and walk every step to the end.
-- Exercise every branch (`goChoice` yes/no paths) — check both sides.
-- For each experiment in `src/config/experiments.ts`, force both variants (`?editor=true&experimentVariant=control|variant_b`) and confirm each renders and advances.
-- Submit email/identity capture with a test address and confirm advancement.
-- Keep the browser console open the whole walk: zero uncaught errors and no failed requests (ignore third-party analytics noise).
-
-## 2. Visual Pass
-
-Run every visual pass at all four default breakpoints (rules in [step-ui-guidelines.md](step-ui-guidelines.md)):
-
-| Breakpoint | Size |
-| --- | --- |
-| small | **375x667** |
-| medium | **393x852** |
-| large | **402x874** |
-| desktop-small | **1280x800** |
-
-- Nothing intersects or overlaps: text never collides with images, cards, badges, or the action bar; modals and dialogs fit the viewport.
-- Continue button sits on an opaque bar at the bottom and stays visible on every step, including while content scrolls.
-- No horizontal scroll, no clipped or truncated content, no broken images.
-- Disabled CTA states render correctly and enable when valid.
-
-## 3. Image Performance
-
-For image edits and every preview-to-production candidate:
-
-- Confirm edited step images are listed in `funnelManifest.assets` and attached
-  to the relevant manifest steps with `assetIds`.
-- Confirm first-viewport images use the framework's priority/preload mechanism.
-- Confirm the shell warms only likely next-step images at low priority, not the
-  full funnel image set.
-- After preview or production publish, confirm build metadata includes the
-  `imageVariants` stage or name why it is unavailable.
-- In the browser/network panel, confirm AVIF/WebP variants are served when the
-  browser advertises support, with the original raster image as fallback.
-
-## 4. Paywall and Checkout (most important)
-
-Test the paywall on every QA run that touches it, pricing, discounts, or experiments — on the paywall step **and** every live paywall variant:
-
-1. **Plans render correctly** — titles, struck-through old price, discounted price, per-day price, featured/preselected plan match `src/config/billing.plans.ts` exactly. Verify discount math.
-2. **Countdown / discount state** — first-stage discount applies on open; timer counts down.
-3. **Checkout opens** — CTA opens the checkout with the selected plan; itemized totals match the selected plan and applied coupon.
-4. **Apple Pay / Google Pay buttons** — wallet slots render (Apple Pay needs Safari/iOS context, Google Pay needs Chrome; on unsupported browsers expect the documented fallback, not a broken gap). If wallets never appear in a supported context, treat as a defect.
-   **Note:** wallet buttons silently fail when the domain and checkout return URLs are not configured in the Stripe dashboard (payment method domains + return URL allowlist). New funnels and new domains must have Stripe configured before wallet QA can pass — if it is not configured, report it as a named blocker, not a pass.
-5. **Close-checkout discount** — close the checkout without paying: the special-offer dialog must appear; accepting it must apply the second-stage (larger) discount to the plan cards and the next checkout's payload. Verify the new prices and coupon id.
-6. **Test payment** — complete a payment with Stripe test card `4242 4242 4242 4242` (test mode) or the approved payment path. Confirm redirect to the subscription-started step with `user_id` preserved.
-7. **Success state** — subscription-started renders, registration/next-step handoff works.
-
-If checkout, payment mode, or test credentials are unavailable, name the skipped item explicitly — a silent skip counts as a fail.
-
-## 5. Registration and Links
-
-- Complete the registration page with valid test data; confirm validation errors on invalid data.
-- Click every legal/support/account link on paywall, checkout, and registration: terms, privacy, subscription policy, money-back, support email.
-
-## 6. Subscription Management
-
-- Open `/manage-subscription?user_id=<test-user>` (or with `stripe_customer_id`).
-- Confirm the subscription list loads and the cancellation flow completes when a test subscription is available; otherwise name it as a skipped item.
-
-## Reporting
-
-Every QA run ends with a short report: stage + URLs tested, steps/branches/variants covered, breakpoint results for small 375x667, medium 393x852, large 402x874, and desktop-small 1280x800, image optimization/preload result when relevant, paywall items 1–7 pass/fail, payment method used, console findings, and named blockers or explicitly skipped items with the reason. Blockers block production unless the user accepts the risk in so many words.

package/template_docs/docs/sdk-api-endpoints.md

@@ -1,78 +0,0 @@
-# SDK API Endpoints
-
-Funnel code should call shared runtime/payment/analytics services, not raw endpoints, unless a new shared helper is being built.
-
-## Runtime Config
-
-`@funnelsgrove/runtime` reads public config from env aliases and exposes `runtimePublicConfig`:
-
-- SDK API base URL.
-- funnel id and funnel version id.
-- SDK publishable key.
-- project id and analytics provider key.
-- support/legal/app-store/deep-link metadata.
-
-`buildMainApiUrl(...)` and `buildSdkHeaders(...)` add the correct SDK base URL and `x-sdk-publishable-key`. Preview frame runtime intentionally suppresses normal SDK calls.
-
-## User and State APIs
-
-Use `apiService` from `@funnelsgrove/runtime`:
-
-- `bootstrapSession(...)`: create/restore the visitor using local user id, URL `user_id`, attribution, email, or name.
-- `updateUser(...)`: persist email/name/progress attributes.
-- `uploadTempPhoto(...)`: upload or locally preview image captures.
-- `getManageSubscriptions()` and `updateSubscription(...)`: subscription management by `user_id` or `stripe_customer_id`.
-- `trackFunnelEvent(...)`, `trackStepStarted(...)`, `trackStepCompleted(...)`: legacy runtime event delivery.
-
-The flow controller already bootstraps the user, persists answer attributes, records completed steps, and connects analytics identity through the shared analytics/runtime integration. Steps should only call `apiService.updateUser(...)` directly when they collect profile data such as checkout email.
-
-## URL User Attributes
-
-The runtime understands these public URL attributes:
-
-- `user_id`: canonical funnel user id.
-- `email`: validated user/customer email.
-- `name`, `fullName`, `full_name`: profile name aliases.
-- `stripe_customer_id`: Stripe customer id for subscription management.
-
-Keep these names stable. If an SDK endpoint or route starts accepting a new identity parameter, update the URL parser, shared services, and docs together.
-
-## Payment APIs
-
-Use `@funnelsgrove/payments`:
-
-- `getPaywallPlans(...)` / `useResolvedPaywallPlans(...)` for `/sdk/public/payments/plans`.
-- `createStripePaymentIntent(...)` for payment intents.
-- `createStripeSubscriptionCheckout(...)` for subscription Elements checkout.
-- `createStripeCheckoutSession(...)` or `redirectToStripeCheckout(...)` for hosted checkout.
-
-Always pass runtime checkout config so published funnels, preview funnels, and local builds resolve the correct funnel id and SDK key.
-
-Checkout endpoints receive `user_id` and `customerEmail` when available. Stripe metadata and `client_reference_id` rely on these values for webhook reconciliation, analytics, and project user support links.
-
-When a funnel sends a configured Stripe `providerPlanId`, public checkout APIs validate that price id against Stripe and fail with a client-visible error if it is missing. Do not silently replace configured price ids with generated `price_data`; dynamic price fallback is only for legacy/catalog entries that have no provider price id.
-
-## Subscription APIs
-
-Use the runtime service methods instead of calling the endpoints directly:
-
-- `GET /sdk/public/users/:user_id/subscription` or `GET /sdk/public/users/subscription?email=...` -> lightweight entitlement status with the resolved `user_id`, `active`, `activeUntil`, and active Stripe subscription ids.
-- `POST /sdk/public/users/:user_id/claim_subscription` -> claim the first unclaimed active subscription for that `user_id`.
-- `apiService.getManageSubscriptions()` -> `GET /sdk/public/subscriptions`.
-- `apiService.updateSubscription(...)` -> `POST /sdk/public/subscriptions/:subscriptionId/:action`.
-
-The status endpoint accepts `user_id` or `email` and returns the resolved `user.user_id` when a funnel user is found. The claim endpoint accepts `funnelId` in the JSON body and only resolves by path `user_id`; it returns `409` if every active subscription is already claimed.
-
-The subscription list endpoint accepts `user_id`, `stripe_customer_id`, and `funnelId`. `user_id` resolves the funnel user first; `stripe_customer_id` can resolve the Stripe customer directly when user id is unavailable. Mutation requires `user_id` or `stripe_customer_id` and supports `cancel` or `renew`.
-
-## Private User Reads
-
-Private SDK user reads are for server-side/admin use only. They can resolve a funnel user by `funnelUserId`, `user_id`, `email`, or `stripeCustomerId` when scoped by the SDK secret key and funnel. This is why paywall email handoff is still useful even when a public link does not know the user id yet.
-
-## Rules
-
-- Keep payloads minimal and typed.
-- Do not log personal data, payment details, SDK keys, or Stripe secrets.
-- Handle loading, unavailable config, API failure, and final failure states in UI.
-- Use local fallbacks only where the shared service already supports them.
-- If an endpoint contract changes, update the shared service, callers, tests, and these docs together.